API Errors Reference

Use 400 when the client sent a value that fails structural validation before any business logic runs. A cursor parameter that isn't valid base64, or that decode...

Use 400 with a Malformed Request Body error when the server cannot parse the payload sent in the HTTP request body. This occurs at the syntax level—for example,...

Use 401 with an expired authentication token error when the client presents a token (such as a JWT, OAuth token, or API token) that is structurally valid and wa...

Use 401 Unauthorized when the request lacks valid authentication credentials. This applies when the client sends no authorization headers/cookies, or when the c...

Use 403 with an Insufficient Scope error when the client's credentials (like an API token or OAuth access token) are valid and authenticated, but the token lack...

Use 404 Resource Not Found when the requested URI does not match any route in the application routing table, or when a dynamic segment of the URI (such as an ID...

Use 405 Method Not Allowed when the HTTP request URI matches a valid path in your routing table, but the specific HTTP method used (e.g. `POST`, `PUT`, `DELETE`...

Use 406 Not Acceptable when the client asks, through proactive content negotiation, for a representation the server is unable to produce. The client expresses i...

Use 408 Request Timeout when the server was prepared to receive a request but the client did not produce a complete one within the time the server was willing t...

Use 409 with an Idempotency Key Conflict error when a client makes a request using an `Idempotency-Key` header that has already been used, but the payload or re...

Use 409 Resource Conflict when the request cannot be completed due to a conflict with the current state of the target resource. The most common use case is a un...

Use 409 Stale Resource Version when implementing optimistic concurrency control (OCC) and the client attempts to update or delete a resource using an outdated v...

Use 412 Precondition Failed when the client attaches a conditional header such as `If-Match` or `If-Unmodified-Since`, and the condition evaluates to false beca...

Use 413 Payload Too Large when the client sends a request body (often a file upload or bulk records batch) that exceeds the maximum size limit configured on the...

Use 415 Unsupported Media Type when the server rejects a request because the request's payload format is not supported. This is typically driven by the `Content...

Use 422 when the request is syntactically valid but semantically wrong. The client sent well formed JSON or query parameters, the shape matches what you expect,...

Use 422 Validation Failed when the request payload is syntactically correct and readable (like valid JSON), but fails to meet the server's business constraints...

Use 429 when the client has sent more requests than your rate limiting policy allows within a given window. The request itself is fine. The client just needs to...