Errors

View as Markdown

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 type and code, never on message.
  • Retry only what can succeed on retry: 429 (after Retry-After), 409 idempotency_in_progress, and 5xx. Use the same Idempotency-Key when you retry a POST, so it can't happen twice.
  • Don't retry other 4xx errors unchanged. Fix the request, or the data, first.
  • Log the request_id. It is in the body and the X-Request-Id header. You can also send your own X-Request-Id (8 to 64 characters from A-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.

Building an integration?

Tell us what you are connecting and we will help you plan it, or book a demo to see the API working.