Errors

Error format, status codes and the full list of error codes.

AveeCare uses conventional HTTP status codes: 2xx for success, 4xx when the request has a problem and 5xx when AveeCare does.

Error format

Every error response has the same JSON body.

Error response · 400

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "request_id": "req_3f9a1c7e5b2d4a6c8e0f1a2b"
  }
}

type is a broad category of the error.
code is stable and machine-readable. Branch on this, not on the message.
message is for humans. Its wording can change.
request_id identifies the request.

Error codes

Code	Status	Meaning	What to do
`invalid_request`	400	The request is malformed or a value failed validation.	Fix the request. The message names the problem.
`unknown_field`	400	The body or query contains a field the endpoint does not accept.	Remove the field. Unknown fields are rejected, not ignored.
`unauthorized`	401	The API key is missing, malformed or revoked.	Check the Authorization header and the key in Settings.
`forbidden`	403	The key is valid but is not allowed to do this.	Use a key that has access, or do not retry.
`insufficient_scope`	403	The key is read-only and the endpoint needs write access.	Create a read + write key.
`not_found`	404	The object does not exist or is not visible to this key.	Check the ID.
`idempotency_conflict`	409	The Idempotency-Key was already used with a different request.	Use a new key for a new request.
`rate_limited`	429	Too many requests.	Wait for the Retry-After seconds, then retry.
`internal_error`	500	Something went wrong on our side.	Retry with backoff. Quote the request_id if it persists.

Request IDs

Every response, successful or not, carries a Request-Id header. Log it. If you contact support about a request, include it so we can find exactly what happened.

Handling errors

Do not retry 400, 401, 403 or 404 responses unchanged. They will fail the same way.
Retry 429 after the Retry-After delay. See Rate limits.
Retry 500 with exponential backoff. For POST requests, send an Idempotency-Key so a retry cannot create a duplicate.

PreviousAuthentication NextPagination