Errors
The error format, every error code, and what to do about each.
Errors are returned as application/problem+json (RFC 9457). Every error carries a stable code that is safe to branch on; title and detail are for people and can change.
Error format
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"code": "not_found",
"detail": "...",
"requestId": "..."
}| Field | Meaning |
|---|---|
code | What went wrong, from the list below. Branch on this |
status | The HTTP status code |
title, detail | A human-readable summary and explanation |
requestId | Include it when you contact Support |
property | For invalid_property, the property at fault |
permission | For forbidden, the permission the key lacks |
existingId | For integration_exists, the integration that already exists |
Error codes
| Code | What it means | What to do |
|---|---|---|
invalid_request | The request is malformed or missing something required | Check the request against the reference and fix it. Do not retry unchanged |
invalid_property | An integration property is invalid | Fix the property named in property. Look up its rules with GET /v1/integration-types/{type} |
unauthenticated | The API key is missing or invalid | Send a valid key as Authorization: Bearer catio_... |
forbidden | The key lacks a permission | Give the key the permission named in permission, or use a key that has it |
not_found | The resource does not exist | Check the id |
integration_exists | An integration with the same identifying properties exists, with different settings | Update the integration in existingId with PATCH instead of creating a new one |
rate_limited | Too many requests | Wait for the Retry-After header, then retry. See Rate Limits and Versioning |
unavailable | The service is temporarily unavailable | Retry with backoff |
internal | Something went wrong on Catio's side | Retry with backoff. If it persists, contact Support with the requestId |
Creating an integration and starting a run are safe to retry, so a retry after unavailable or internal does not create duplicates.
Errors about an integration's data, such as a role that cannot be assumed, are not API errors. They appear in the run's messages. See Quickstart.
Updated 15 days ago
Did this page help you?
