Errors and retries | CharterOps

Errors use application/problem+json. Read the status and machine-readable type; the human-readable detail may change.

Problem fields

The response includes type, title, status, detail, instance and request_id. Validation failures may include field-level errors. Quota failures also include reset_at and upgrade_url.

Keep the request_id with your own diagnostic record. The dashboard’s Logs tab finds a request by that ID. Remove credentials and private client or trip details before sharing logs.

Decide what to do

400 or 422: correct the request. Repeating the same invalid body will fail again.
401: check or replace the credential.
403: check scopes, organization role and plan access.
404: the resource does not exist or is unavailable to this caller.
409: reload current state and resolve the conflict before retrying.
413: send a smaller body. A JSON body may be at most 1 MiB.
429: follow Retry-After and the quota or throttle problem details.
503 overloaded: the API was briefly out of database connections. Wait Retry-After seconds, then retry.
5xx: use a bounded retry with backoff and jitter. Surface a failure when retries are exhausted.

not_connected means a required external integration is unavailable. not_built_yet identifies an unavailable capability. Neither means that a request succeeded.

Idempotency

Create and transition operations that require Idempotency-Key declare the header in the reference. Generate one value for one logical action. Reuse that value and the same request when retrying after an uncertain network result; do not generate a new key for every attempt.

Key creation is intentionally different: its secret is returned once. A replay can return 409 key_already_created; revoke and replace a lost key rather than expecting the secret to be recovered.

Common problem types

Type	Meaning
`validation_error`	One or more inputs need correction.
`unauthorized`	Authentication is missing or invalid.
`forbidden`	The caller does not have permission.
`not_found`	The requested resource is unavailable to this caller.
`conflict`	The action conflicts with the current state.
`plan_feature`	The current plan does not include this capability.
`quota_exceeded`	The organization’s period allowance is exhausted.
`rate_limited`	A request throttle has been reached.
`payload_too_large`	The request body is larger than the limit.
`not_built_yet`	The capability is not implemented.
`not_connected`	A required integration is not connected.
`provider_unavailable`	An external provider could not complete the operation.
`internal`	The server could not complete the request.
`overloaded`	Every database connection was busy. Retry after `Retry-After`.

The response’s X-Request-Id matches request_id in the problem body. Individual operations can return more specific conflict types; consult their reference entries.