# Errors

> 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:

```json
{
  "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:

```json
{
  "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](https://continuumlearn.com/developers/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](https://continuumlearn.com/developers/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.
