Migrate error handling from v1
v1 returns errors as {"error": "..."}, {"msg": "..."}, {"message": "..."} or plain-text Unauthorized and Forbidden. Every /v2 error response is one JSON envelope: { "error": { "type", "code", "message", "param"?, "details"?, "request_id" } }. Branch on error.type and error.code, which are stable; message and details can change. request_id equals the x-request-id response header; send it to Brellium support when you report a problem.
POST /v2/oauth/token uses the envelope only for 429 RATE_LIMITED and 502 BAD_GATEWAY. Its other errors, such as the 401 with access_denied for a wrong client_secret or an unknown client_id, come in the OAuth error format with no request_id. For those, send Brellium support the x-request-id response header instead.
A request can also get a bare 403, 413, 414 or 431, with no JSON body and no x-request-id. A 413, 414 or 431 means the body, the URL or the headers were too large. For the causes of a bare 403, see Rate limits and errors.
The table maps the common v1 errors to their v2 status, type and code:
| v1 | v2 | type / code |
|---|---|---|
401, plain text Unauthorized or {"error"} |
401 |
authentication_error / UNAUTHORIZED (missing header, or invalid or expired token) |
400 {"error": "User already exists"} |
409 |
conflict_error / USER_EXISTS, INVITATION_PENDING or INVITATION_EXPIRED |
400 for a bad body |
400 |
invalid_request_error / VALIDATION_ERROR with one details object per problem; INVALID_CONTENT_TYPE when the body is sent without Content-Type: application/json; HTTP_ERROR when the body is not valid JSON |
500 for a missing audit in a flag update |
404, or a per-item NOT_FOUND inside the 200 result of a batch update |
not_found_error / NOT_FOUND |
| (none) | 429 |
rate_limit_error / RATE_LIMITED, with Retry-After |
An endpoint that takes an id in the path returns 404 NOT_FOUND when your organization has no record with that id; another organization's id and a deleted record return 404 too. A server error returns 500 with api_error / INTERNAL_ERROR.
For every code and the retry rules, see Rate limits and errors. Each resource page lists the errors of its own endpoints, and Migrate from v1 links to each of them.
Next
Rate limits and errors
The rate limits and their headers, how to retry a 429, and every error code.
Migrate from v1
Move an integration from the v1 API to v2, one resource at a time.
