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": "..."
}
FieldMeaning
codeWhat went wrong, from the list below. Branch on this
statusThe HTTP status code
title, detailA human-readable summary and explanation
requestIdInclude it when you contact Support
propertyFor invalid_property, the property at fault
permissionFor forbidden, the permission the key lacks
existingIdFor integration_exists, the integration that already exists

Error codes

CodeWhat it meansWhat to do
invalid_requestThe request is malformed or missing something requiredCheck the request against the reference and fix it. Do not retry unchanged
invalid_propertyAn integration property is invalidFix the property named in property. Look up its rules with GET /v1/integration-types/{type}
unauthenticatedThe API key is missing or invalidSend a valid key as Authorization: Bearer catio_...
forbiddenThe key lacks a permissionGive the key the permission named in permission, or use a key that has it
not_foundThe resource does not existCheck the id
integration_existsAn integration with the same identifying properties exists, with different settingsUpdate the integration in existingId with PATCH instead of creating a new one
rate_limitedToo many requestsWait for the Retry-After header, then retry. See Rate Limits and Versioning
unavailableThe service is temporarily unavailableRetry with backoff
internalSomething went wrong on Catio's sideRetry 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.


Did this page help you?