Skip to content
MelonforceAPI docs

Errors

What an error answer holds, when to send a request again, and what every error code means.

When a request fails, the API answers with a status of 400 or higher and a JSON body that says what went wrong.

The error body

Every error has the same shape:

An error with details
{
  "error": {
    "code": "VALUE_INVALID",
    "details": {
      "columnId": "stage",
      "reason": "unknown_label",
      "message": "The column has no such label."
    }
  }
}
  • code is a string, such as NOT_FOUND. Read the code, not only the status: several codes share one status.
  • New codes can be added without a new API version. Treat a code you do not know by its HTTP status. For example, handle an unknown 409 code as you handle other 409 answers.
  • details is optional. Only some codes have it, and its shape depends on the code. Each code's details are in the list of codes below.
  • Every error answer has Cache-Control: no-store, so nothing on the way caches it.
An error without details
HTTP/1.1 404 Not Found
Content-Type: application/json
Cache-Control: no-store

{"error":{"code":"NOT_FOUND"}}

When to send a request again

Send it again, after a wait:

  • 429 RATE_LIMITED: you made too many calls. Wait the number of seconds in the Retry-After header, then send it again. See Rate limits.
  • 503 UNAVAILABLE: others changed the same thing at the same moment, and nothing was written. Wait the seconds in Retry-After, then send it again.
  • 409 IDEMPOTENCY_KEY_REUSED with Retry-After: a request with the same Idempotency-Key is still running. Wait, then send the same request with the same key. If the first one succeeded, you get its answer back. See Idempotency keys.
  • 500 INTERNAL: something went wrong on our side. Try again later. Send an Idempotency-Key when you create a board or an item, or send a batch, so that sending it again never creates twice. Other creates, such as a group's, do not read it.

Do not send it again unchanged:

  • 400: the request is wrong. Fix it first.
  • 401: the key does not work. The same key gets the same answer.
  • 403: the key may not do this.
  • 404: the thing does not exist in your workspace, or was deleted.

The same goes for 413, and for a 409 without Retry-After, such as IDEMPOTENCY_KEY_REUSED for a key you used with a different request. For 409 GROUP_ORDER_MISMATCH, read the board's groups again, then send an order that has every live group once.

401: the key does not work

Every key that does not work gets the same answer: 401 UNAUTHENTICATED, with WWW-Authenticate: Bearer. The answer never says why. It can be any of these:

  • The header is not Authorization: Bearer followed by the key.
  • The key is from another environment, or is not a key at all.
  • The key is unknown, revoked or expired.
  • The person who made the key is no longer an owner or admin of the workspace.
  • The workspace is gone, suspended or closed.

A request with no Authorization header gets 401 UNAUTHENTICATED too, without the WWW-Authenticate header.

A key in the right format that does not work, such as an unknown, revoked or expired key, also counts against a limit for the address it came from. Past 30 such keys in 60 seconds, more of them get 429 RATE_LIMITED instead. A malformed header or key gets 401 and is not counted. See Rate limits.

An owner or admin can check the key in the app, under API keys in the sidebar's Workspace group. See Authentication.

403: a key may not do this

A key gets 403 FORBIDDEN in three cases:

  • A route for people signed in to the app. Account settings, such as changing members, invitations and API keys, are not open to keys. These routes answer before they read anything, with details.reason set to session_required. They are not in these docs.
  • Someone else's update. A key can edit and delete only its own posts. Editing or deleting anyone else's comment or post answers 403 FORBIDDEN with no details.
  • Claiming an item. The app's Claim action (POST /v1/items/{itemId}/claim) is for people, so a key gets details.reason set to not_a_person. To set an item's person, update the item.
A route for signed-in people only
{
  "error": {
    "code": "FORBIDDEN",
    "details": { "reason": "session_required" }
  }
}

404: not found

404 NOT_FOUND means there is no such board, column, view, group, item or update in your key's workspace. It also covers:

  • An ID from another workspace. It answers as if it did not exist, and nothing is changed.
  • An ID that is not shaped like one of ours, such as a board ID without its brd_ prefix.
  • A restore of a board, column or group that is not in the trash.
  • A delete of something that is already deleted.
  • A path that no route has.
  • Something deleted while your request ran. Nothing is written.

A groupId in a request body is different: one that is not a live group of the board answers 400 GROUP_INVALID, not 404. In a batch, GROUP_INVALID is the code of that entry. One not shaped like a group ID answers 400 INVALID_REQUEST, or is an INVALID_REQUEST entry of a batch.

Error codes

Every code an API key can get, sorted by status. Each code has its own link, such as /docs/errors#NOT_FOUND. The reference lists, for each route, the codes it can answer.

BATCH_INVALID400

Some entries of the batch are bad, so nothing was written. details.errors lists each problem with the entry's index.

error.details

errors

array of BatchEntryErrorrequired

One for each problem, in the order of the entries.

  • At least 1 item
Show 4 fieldsHide 4 fields
index

integerrequired

The entry's place in the list, from 0.

  • At least 0
code

stringrequired

What is wrong, as an error code: VALUE_INVALID, NOT_FOUND, GROUP_INVALID or INVALID_REQUEST.

columnId

stringoptional

The column whose value is the problem, when it is one column's value.

message

stringrequired

A plain description of the problem.

CHANGE_PLACE_UNKNOWN400

The after place is one the changes feed does not know: higher than your workspace's latest. Ask without after for the latest place, then load the board again.

CURSOR_INVALID400

The cursor (or the updates feed's before) cannot be read. A cursor whose row no longer exists at all can be refused too, when the API must read that row again to go on. Start again from the first page.

CURSOR_MISMATCH400

The cursor came from a different query, or was made when a relative date in the query, or its grouping by a date column, covered other days. Send it with the query it came from, or start again from the first page.

GROUP_INVALID400

A group named in the body is not a live group of this board: unknown, deleted, or another board's or workspace's. An item create's or move's groupId answers it with no details; a group create's before answers it with details.field before. In a batch it is an entry's code inside BATCH_INVALID. A group in the path that is not found answers 404 instead.

error.details

field

stringrequired

The field at fault: before, the group a new group was to go right before.

  • Always "before"
GROUPING_NOT_ALLOWED400

The query, or a view's group, groups by Name, by a column that holds no value (a button) or by one that allows several values. An items query sent as fields and a view's create or update answer it; with other problems besides, they answer QUERY_INVALID. A saved view run by its ID leaves such a grouping out instead. details.issues names it.

error.details

issues

array of objectrequired

One entry for each problem in the query.

Show 3 fieldsHide 3 fields
path

array of one of string, integerrequired

Where in the query, as keys and indexes from the top: filter, conditions, 0, column.

code

stringrequired

What is wrong there, such as not_groupable. Read codes you do not know as invalid.

message

stringrequired

A short note for a person reading the error.

INVALID_REQUEST400

The body, a query parameter or the Idempotency-Key does not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carry details.reason, which says why, and details.field, which names the field when one is at fault.

error.details

reason

stringrequired

Why: unknown_column or wrong_type (the column field names is missing or of the wrong type), include_time_locked (a date column's includeTime cannot change), main_person_single (the person column Claim assigns must hold one person), same_type, settings_invalid or settings_required (a type change), order_mismatch (a column order that is not every column once) or last_view (a board keeps at least one view).

  • One of "unknown_column", "wrong_type", "include_time_locked", "main_person_single", "same_type", "settings_invalid", "settings_required", "order_mismatch", "last_view"
field

stringoptional

The field at fault, such as statusColumnId or afterColumnId, when the reason is about one field.

QUERY_INVALID400

The query names a column the board lacks, an operator or value that does not fit its column, a column that cannot be sorted, or Me, which a key cannot use (sent, or in a saved view). Or the query is too large to run as one statement. Most answers say where in details.issues.

error.details

issues

array of objectrequired

One entry for each problem in the query.

Show 3 fieldsHide 3 fields
path

array of one of string, integerrequired

Where in the query, as keys and indexes from the top: filter, conditions, 0, column.

code

stringrequired

What is wrong there, such as not_groupable. Read codes you do not know as invalid.

message

stringrequired

A short note for a person reading the error.

VALUE_INVALID400

A value does not fit its column, names a label, option or person that does not exist, is too large, or sits under a key that is not a live column of the board. Nothing is written; details.columnId names the column.

error.details

columnId

stringrequired

The column whose value was refused.

reason

stringoptional

Why: invalid (wrong type or form), unknown_label, unknown_option, unknown_person (not a current member) or too_large.

  • One of "invalid", "unknown_label", "unknown_option", "unknown_person", "too_large"
message

stringoptional

A short note for a person reading the error.

UNAUTHENTICATED401

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

FORBIDDEN403

The key may not do this. Editing or deleting an update someone else wrote answers it with no details; a route for people signed in to the app answers it with details.reason session_required; claiming an item, which is for people, answers it with details.reason not_a_person.

error.details

reason

stringrequired

Why: session_required means the route is for people signed in to the app, not for API keys; not_a_person means the route acts as a person, such as Claim. workspace_not_active answers a person signed in to the app who makes a key in a workspace that is not active; a key never gets it.

  • One of "session_required", "not_a_person", "workspace_not_active"
NOT_FOUND404

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

COLUMN_ID_TAKEN409

The column ID is already used on the board, by a deleted column too. Choose another.

COLUMN_PROTECTED409

The Name column cannot be changed with a PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.

GROUP_ORDER_MISMATCH409

The order is not exactly the board's live groups, each once: a group is missing, extra, repeated, deleted or another board's, or a group was created, deleted or restored while the request ran. Nothing was written; read the groups again and send the whole order.

IDEMPOTENCY_KEY_REUSED409

The Idempotency-Key was used before with a different request, or a request with the same key is still running. In the second case, send it again after Retry-After seconds.

Retry-After: 1 second

LAST_GROUP409

The group is the board's last live group, and a board always keeps one, so it cannot be deleted. Create another group first.

LIMIT_REACHED409

A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert. details.limit names it and details.max gives the cap.

error.details

limit

stringrequired

What is full: columns or views (per board), groups (live groups per board, on a group create or restore), conversion-values (the values one type change would convert) or conversion-bytes (their size).

max

integerrequired

The cap.

  • At least 0
NOTES_CONFLICT409

The save's baseVersion is not the notes' current version, so nothing was written. details.note holds the notes as they are now; to overwrite them, send again with its version.

error.details

note

Noterequired

The notes as they are now, with their current version.

Show 6 fieldsHide 6 fields
markdown

stringrequired

The notes, in Markdown. Empty when none are saved.

version

integerrequired

Raised by one on each save; 0 when none are saved. Send it as baseVersion to save.

  • At least 0
updatedAt

string or nullrequired

When the notes were last saved. Null when none are saved.

  • Format date-time (ISO 8601)
updatedBy

string or nullrequired

Who saved last: a person's user ID or an API key's ID. Null when none are saved.

  • 1 to 64 characters
updatedByType

string or nullrequired

Whether updatedBy is a person (member) or an API key (api_key). Null when none are saved.

  • One of "member", "api_key"
apiKeys

array of NamedApiKeyrequired

The API key named by updatedBy, when a key saved last; otherwise empty.

Show 3 fieldsHide 3 fields
id

stringrequired

The key's ID: apk_ and 21 characters. Never the key itself.

  • Pattern ^apk_[0-9a-z]{21}$
name

stringrequired

The name the key was given.

revoked

booleanrequired

True when the key was revoked. What it did stays.

PAYLOAD_TOO_LARGE413

The body is over its route's size limit. A save of notes with too many characters answers it too, with details.limit notes and details.max.

error.details

limit

stringrequired

What is too long: notes, the Markdown of an item's notes.

  • Always "notes"
max

integerrequired

The most characters allowed.

  • At least 0
RATE_LIMITED429

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

Retry-After: 10 seconds

INTERNAL500

Something went wrong on our side. Try again later.

UNAVAILABLE503

Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the Idempotency-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

Retry-After: 1 second