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:
{
"error": {
"code": "VALUE_INVALID",
"details": {
"columnId": "stage",
"reason": "unknown_label",
"message": "The column has no such label."
}
}
}codeis a string, such asNOT_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.
detailsis 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.
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 theRetry-Afterheader, 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 inRetry-After, then send it again. - 409
IDEMPOTENCY_KEY_REUSEDwithRetry-After: a request with the sameIdempotency-Keyis 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 anIdempotency-Keywhen 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: Bearerfollowed 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.reasonset tosession_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
FORBIDDENwith no details. - Claiming an item. The app's Claim action (
POST /v1/items/{itemId}/claim) is for people, so a key getsdetails.reasonset tonot_a_person. To set an item's person, update the item.
{
"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.errorslists each problem with the entry'sindex.error.detailserrorsarray of BatchEntryErrorrequired
One for each problem, in the order of the entries.
- At least 1 item
Show 4 fieldsHide 4 fields
indexintegerrequired
The entry's place in the list, from 0.
- At least 0
codestringrequired
What is wrong, as an error code:
VALUE_INVALID,NOT_FOUND,GROUP_INVALIDorINVALID_REQUEST.columnIdstringoptional
The column whose value is the problem, when it is one column's value.
messagestringrequired
A plain description of the problem.
- CHANGE_PLACE_UNKNOWN400
The
afterplace is one the changes feed does not know: higher than your workspace's latest. Ask withoutafterfor 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
groupIdanswers it with no details; a group create'sbeforeanswers it withdetails.fieldbefore. In a batch it is an entry's code insideBATCH_INVALID. A group in the path that is not found answers 404 instead.error.detailsfieldstringrequired
The field at fault:
before, the group a new group was to go right before.- Always
"before"
- Always
- 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 answerQUERY_INVALID. A saved view run by its ID leaves such a grouping out instead.details.issuesnames it.error.detailsissuesarray of objectrequired
One entry for each problem in the query.
Show 3 fieldsHide 3 fields
patharray of one of string, integerrequired
Where in the query, as keys and indexes from the top:
filter,conditions,0,column.codestringrequired
What is wrong there, such as
not_groupable. Read codes you do not know as invalid.messagestringrequired
A short note for a person reading the error.
- INVALID_REQUEST400
The body, a query parameter or the
Idempotency-Keydoes 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 carrydetails.reason, which says why, anddetails.field, which names the field when one is at fault.error.detailsreasonstringrequired
Why:
unknown_columnorwrong_type(the columnfieldnames is missing or of the wrong type),include_time_locked(a date column'sincludeTimecannot change),main_person_single(the person column Claim assigns must hold one person),same_type,settings_invalidorsettings_required(a type change),order_mismatch(a column order that is not every column once) orlast_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"
- One of
fieldstringoptional
The field at fault, such as
statusColumnIdorafterColumnId, 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.detailsissuesarray of objectrequired
One entry for each problem in the query.
Show 3 fieldsHide 3 fields
patharray of one of string, integerrequired
Where in the query, as keys and indexes from the top:
filter,conditions,0,column.codestringrequired
What is wrong there, such as
not_groupable. Read codes you do not know as invalid.messagestringrequired
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.columnIdnames the column.error.detailscolumnIdstringrequired
The column whose value was refused.
reasonstringoptional
Why:
invalid(wrong type or form),unknown_label,unknown_option,unknown_person(not a current member) ortoo_large.- One of
"invalid","unknown_label","unknown_option","unknown_person","too_large"
- One of
messagestringoptional
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 anAuthorizationheader, it comes withWWW-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.reasonsession_required; claiming an item, which is for people, answers it withdetails.reasonnot_a_person.error.detailsreasonstringrequired
Why:
session_requiredmeans the route is for people signed in to the app, not for API keys;not_a_personmeans the route acts as a person, such as Claim.workspace_not_activeanswers 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"
- One of
- 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-Keywas used before with a different request, or a request with the same key is still running. In the second case, send it again afterRetry-Afterseconds.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.limitnames it anddetails.maxgives the cap.error.detailslimitstringrequired
What is full:
columnsorviews(per board),groups(live groups per board, on a group create or restore),conversion-values(the values one type change would convert) orconversion-bytes(their size).maxintegerrequired
The cap.
- At least 0
- NOTES_CONFLICT409
The save's
baseVersionis not the notes' current version, so nothing was written.details.noteholds the notes as they are now; to overwrite them, send again with itsversion.error.detailsnoteNoterequired
The notes as they are now, with their current
version.Show 6 fieldsHide 6 fields
markdownstringrequired
The notes, in Markdown. Empty when none are saved.
versionintegerrequired
Raised by one on each save; 0 when none are saved. Send it as
baseVersionto save.- At least 0
updatedAtstring or nullrequired
When the notes were last saved. Null when none are saved.
- Format
date-time(ISO 8601)
- Format
updatedBystring 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
updatedByTypestring or nullrequired
Whether
updatedByis a person (member) or an API key (api_key). Null when none are saved.- One of
"member","api_key"
- One of
apiKeysarray of NamedApiKeyrequired
The API key named by
updatedBy, when a key saved last; otherwise empty.Show 3 fieldsHide 3 fields
idstringrequired
The key's ID:
apk_and 21 characters. Never the key itself.- Pattern
^apk_[0-9a-z]{21}$
- Pattern
namestringrequired
The name the key was given.
revokedbooleanrequired
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.limitnotesanddetails.max.error.detailslimitstringrequired
What is too long:
notes, the Markdown of an item's notes.- Always
"notes"
- Always
maxintegerrequired
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-Afterseconds.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-Keywas kept in parts and a part is gone. Nothing was written; send it again afterRetry-Afterseconds.Retry-After: 1 second