Errors
CardioBridge uses conventional HTTP status codes to indicate the success or failure of a request. Error responses include a JSON body with a machine-readable code and a human-readable error message.
Error catalog
| Status | Code | When it happens | How to handle |
|---|---|---|---|
| 400 | validation_error | A required field is missing or a value failed validation. | Inspect the error message, fix the request body, and resubmit. |
| 401 | missing_api_key | No x-api-key header was provided. | Add the x-api-key header to every request. |
| 401 | invalid_api_key | The API key is unknown or has been revoked. | Generate a new key in the app under Integrations and update your config. |
| 404 | not_found | The referenced intake or job does not exist. | Verify the reference; it may belong to another organisation or have been mistyped. |
| 500 | server_error | Something went wrong on our end. | Retry with exponential backoff; if it persists, contact support. |
Retrying
Treat
5xx responses as transient: retry with exponential backoff (e.g. 1s, 2s, 4s, 8s) and a capped number of attempts. Do not retry 4xx errors — fix the request first.