Errors
The careCycle API error format, every error code, and how to recover from each one.
The careCycle API uses standard HTTP status codes. A 2xx status means the
request succeeded. Errors return a JSON body with a human-readable message and
a machine-readable code.
Error format
{
"message": "A customer with this MBI already exists",
"code": "CUSTOMER_ALREADY_EXISTS"
}Branch on code (or on the HTTP status when no code you recognize is present).
Do not parse message: it is written for people and can change.
Some errors carry extra fields:
| Status | Extra field | Contents |
|---|---|---|
400, 409 | details | An object with more context about the problem, when available |
422 | errors | One entry per invalid field: path, message, code, and sometimes expected and received |
422 | failedRecords | Sync endpoints only: identifiers of the records that failed validation |
429 | retryAfter | Seconds to wait before retrying. See Rate limits |
A validation error looks like this:
{
"message": "Validation failed",
"code": "VALIDATION_ERROR",
"errors": [
{
"path": ["email"],
"message": "Invalid email address",
"code": "invalid_format"
}
]
}Error codes
| Status | Code | Meaning | How to recover |
|---|---|---|---|
400 | BAD_REQUEST | The request is well formed but not valid for this operation | Read message and details, fix the request, and retry. Retrying unchanged fails again |
401 | UNAUTHORIZED | The API key is missing or invalid | Send a valid key in the x-api-key header. See Authentication |
403 | FORBIDDEN | The key is valid but lacks the capability this endpoint needs | Create a key with the required capability. Retrying with the same key fails again |
404 | NOT_FOUND | The resource does not exist, or your key can't access it | Check the ID. Do not retry |
409 | CONFLICT | The request conflicts with the current state, for example a duplicate | Fetch the current state, then decide whether to update the existing resource or change the request |
422 | VALIDATION_ERROR | The request failed schema validation | Fix each field listed in errors, then retry |
429 | RATE_LIMIT_EXCEEDED | The key exceeded its rate limit | Wait retryAfter seconds, then retry. See Rate limits |
500 | INTERNAL_SERVER_ERROR | Something went wrong on careCycle's side | Retry with exponential backoff. If it persists, contact support |
503 | SERVICE_UNAVAILABLE | The service is temporarily unavailable | Retry with exponential backoff |
Endpoint-specific codes
Some endpoints return a more specific code with one of the statuses above.
For example, creating a customer whose MBI is already on file returns 409
with CUSTOMER_ALREADY_EXISTS, and booking an appointment slot that was just
taken returns 409 with SLOT_NO_LONGER_AVAILABLE. Each endpoint page lists
the statuses it can return. Treat any code you don't recognize according to its
HTTP status.
Server errors
5xx responses always use a generic message, so the body does not explain the
failure. Before retrying a POST that creates something, check whether the
first attempt succeeded, to avoid creating a duplicate.
Errors outside the standard format
A few errors are returned before a request reaches an endpoint and use an
error field instead of code:
- Malformed JSON returns
400with"error": "Invalid JSON". - Request bodies over 2 MB return
413.
Fix the request body before retrying.
Request IDs
Every response includes an X-Request-Id header. Include it when you contact
careCycle support about a specific request.