Errors
Use the HTTP status and JSON code to decide what to do next.
Read the error body
The shared v1 JSON error helper returns code and message. The code identifies the error category; the message gives details.
{
"code": "BAD_REQUEST",
"message": "limit: Required"
}This example is returned when the paginated members request omits limit. There is no shared error envelope around these two fields.
Status and error codes
| HTTP status | Code | Action |
|---|---|---|
| 400 | BAD_REQUEST | Check JSON, identifiers, parameters and resource constraints. |
| 401 | UNAUTHORIZED | Supply a valid, non-revoked bearer key. |
| 403 | FORBIDDEN | Check scopes, ownership, friend permissions and feature access. |
| 404 | NOT_FOUND | Check the identifier and account. Some access denials deliberately use 404. |
| 409 | CONFLICT | Resolve the resource conflict before retrying. |
| 429 | RATE_LIMITED | Pause and retry with bounded backoff. |
| 500 | INTERNAL, INTERNAL_ERROR or INTERNAL_SERVER_ERROR | The error mapper reports an internal failure. Avoid assuming a write did not happen. |
| 503 | PRECONDITION_FAILED | A required storage or service prerequisite is unavailable. This code is mapped to 503, not 412. |
Allow for route-specific responses
The messaging mapper preserves service error codes and uses HTTP 400 as its fallback for unmapped service codes. Validation in the v1 handlers uses 400; there is no shared 422 validation response.
Not every failure has JSON
The member-media service returns empty bodies for its 404 and 503 responses. Authentication failures on that route still use the JSON error helper. Check the response content type and endpoint reference before parsing JSON; uncaught infrastructure errors are not guaranteed to use the v1 shape.
See the member-media reference for this exception, and each endpoint’s response tabs for its documented errors.