In short
Every API v2 error has the same JSON shape - error.type for the category, error.code for the specific reason when there is one, a human-readable message, optional details and a request_id. Branch on type and code, never on the message.
The error envelope
Every error response from /api/v2, whatever went wrong, has this shape:
{
"error": {
"type": "conflict",
"code": "user_exists",
"message": "A user with this email is already a member of this team.",
"details": { "user_id": 2 }
},
"request_id": "01M70A2C4QQHHMBFPZ6FGSWV6E"
}
| Field | Always present | Meaning |
|---|---|---|
error.type |
Yes | The category of error, one of the types below. Stable. |
error.code |
No | The specific reason, for errors that have one (see the codes table). Stable. |
error.message |
Yes | A sentence for humans. It may be reworded at any time, so don't parse it. |
error.details |
No | Extra data: field messages for a validation error, or ids that explain a conflict. |
request_id |
Yes | The same value as the X-Request-Id response header. |
Unexpected server errors never include exception text, file names or stack traces.
Error types
| HTTP status | error.type |
When |
|---|---|---|
| 401 | authentication_error |
The key is missing, unknown, revoked or expired. |
| 403 | permission_error |
The key lacks the scope the endpoint needs, the team's subscription is inactive, or the team is in the read-only grace period and this is a write. |
| 404 | not_found |
The resource doesn't exist, or belongs to another team, or the user is not a member of this team. |
| 405 | invalid_request |
The endpoint exists but not with this HTTP method. |
| 409 | conflict |
The request clashes with the current state, for example a full course or an existing user. Always has a code. |
| 422 | validation_error |
A field is missing or invalid. details maps each field to its messages. |
| 422 | invalid_request |
The request is well formed but can't be acted on, for example a bad filter value. Always has a code. |
| 429 | rate_limited |
Too many requests. Wait for the number of seconds in the Retry-After header. |
| 500 | server_error |
Something went wrong on our side. Retry later, and quote the request_id if it keeps happening. |
A validation error lists every invalid field:
{
"error": {
"type": "validation_error",
"message": "The given data was invalid.",
"details": {
"email": ["The email field is required."],
"custom_fields.17": ["Must be a date in Y-m-d format."]
}
},
"request_id": "01M70A2C4ZK87AY72XET99Q4E0"
}
Error codes
error.code is set on every 409 conflict and every 422 invalid_request. These are all the codes API v2 returns today. New codes may be added (see Versioning), so treat an unknown code like its type.
| Code | Status | Returned by | What it means and what to do |
|---|---|---|---|
invalid_filter |
422 | GET /courses, GET /credentials |
A filter has a value the API doesn't accept, for example a visibility other than public or private, an unsupported language, a credential state that isn't valid, revoked, expired or unsigned, or a date that isn't ISO 8601. The message names the filter. |
user_exists |
409 | POST /users |
That email is already a member of this team. details.user_id is the existing user: update them with PATCH instead. |
user_protected |
409 | Users, sign-in links | The account is protected (an administrator or similar, platform staff, a member of another team, or a linked presenter) and the API may not make this change. Change it in Manage instead. See Users. |
external_source_read_only |
422 | POST/PATCH /users |
You tried to write an external id under a source other than your team's own. Leave external_source out to use your team's source. |
external_identity_locked |
409 | POST/PATCH /users |
The user already has an external id from another source (details.source), such as a WordPress connection. It can't be replaced through the API. |
external_id_taken |
409 | POST/PATCH /users |
Another member of this team already has that external id (details.user_id). Check your system for a duplicate record. |
group_not_found |
422 | POST/PATCH /users |
One or more group_ids aren't groups in this team (details.group_ids). |
group_rules_managed |
409 | Users, group members | The group's membership is managed by auto-assign rules, so members can't be added or removed by hand. |
group_locked |
409 | PATCH/DELETE /groups/{id} |
The group is locked: it can't be renamed, given a new reference or deleted. |
unsupported_characters |
422 | POST/PATCH /groups |
Group names can only use Western European (Latin-1) characters at present. |
course_full |
409 | Enrolments | The course has no spaces left (details.spaces, details.remaining). Send waitlist: true to add the user to the waiting list, or ignore_capacity: true to enrol anyway. |
required_training |
409 | DELETE /users/{user}/enrolments/{course} |
An active training requirement covers this user on this course, so the enrolment can't be removed. Exempt the learner or remove them from the requirement's audience first. |
prerequisites_unmet |
422 | Enrolments | Only when you sent check_prerequisites: true: the user hasn't completed the courses in details.courses. |
ambiguous_user |
422 | POST /enrolments |
Identify the user with exactly one of user_id, email or external_id. |
invalid_idempotency_key |
422 | Any POST | The Idempotency-Key header must be 1 to 255 characters from A-Z a-z 0-9 _ - : .. |
idempotency_key_reused |
422 | Any POST | That Idempotency-Key was already used in the last 24 hours with a different path or body. Use a new key for a new request. |
idempotency_in_progress |
409 | Any POST | A request with the same Idempotency-Key is still being processed. Retry after the Retry-After header (1 second). |
idempotency_key_unreadable |
409 | Any POST | The stored result for that Idempotency-Key could not be read, so the request was not run again. Use a new key. |
user_deactivated |
409 | POST /users/{id}/sign-in-links |
The user has no role in this team, so they can't be signed in. Reactivate them first. |
delivery_in_progress |
409 | POST /webhook-endpoints/{id}/deliveries/{delivery_id}/redeliver |
The delivery is still pending or waiting for a retry. Only a delivery that has succeeded or failed can be redelivered: read it again later. |
Apart from redelivery, webhook endpoint management has no codes of its own: a refused URL, a team's 11th endpoint or an unknown event type is a 422 validation_error with the reason under details.url or details.events.
Handling errors well
- Branch on
typeandcode, never onmessage. - Retry only what can succeed on retry:
429(afterRetry-After),409 idempotency_in_progress, and5xx. Use the sameIdempotency-Keywhen you retry a POST, so it can't happen twice. - Don't retry other
4xxerrors unchanged. Fix the request, or the data, first. - Log the
request_id. It is in the body and theX-Request-Idheader. You can also send your ownX-Request-Id(8 to 64 characters fromA-Z a-z 0-9 . _ -) and it will be echoed back and used in our logs, which makes a request easy to trace from both ends.
Frequently asked questions
Why do I get 404 for a user I know exists?
Users are platform-wide accounts, but the API only sees members of your team. A user who isn't a member of the key's team returns 404, exactly as if they didn't exist.
Why is a missing scope a 403 and not a 404?
The scope check happens before the API looks anything up, so it says which scope is missing without revealing whether the resource exists.