Errors
{ "error": { "code": "…", "message": "…", "request_id": "…", "details": [ … ] } }
| Code | Status | Meaning |
|---|---|---|
validation_failed | 400 / 422 | The body did not match the schema. details names the path. |
unauthorized | 401 | No or invalid session or key. |
forbidden | 403 | Permission missing. |
not_found | 404 | Does not exist, or belongs to another workspace. |
conflict | 409 | State conflict; the message says which. Includes an ambiguous idempotency lease: query the resource before retrying. |
rate_limited | 429 | Honour retry-after. |
internal_error | 500 | Quote the request id. |
provider_unavailable | 502 / 503 | The provider could not be reached. |
idempotency_key_required | 400 | Missing or over 255 characters. |
idempotency_conflict | 409 | Same key, different request. |
idempotency_in_progress | 409 | The first request is still running. |
live_entitlement_required | 403 | Live needs an entitlement this workspace does not hold. |
live_operations_disabled | 403 | The deployment's live switch is off. |
environment_mismatch | 403 / 409 | A key naming the other environment, or a connection bound elsewhere. |
live_key_in_test_environment | 422 | Refused before storage. details[].guidance says what to do. |
test_key_in_live_environment | 422 | The reverse. |
credential_invalid / credential_prefix_rejected | 422 | Shape or provider validation failed. |
credential_revoked | 409 | The connection's credential was revoked. |
connection_not_active | 409 | Not ACTIVE or dispatchable. |
connection_kind_invalid | 422 | A pooled demo connection where a direct one is required. |
provider_validation_failed | 422 | The provider rejected the credential. |
webhook_secret_missing | 409 | The connection has no secret for this webhook kind. |
no_eligible_route | 422 | No connection survived the filters. details carries the route decision id. |
intent_state_invalid | 409 | The intent is not in a state that allows this. |
amount_invariant_violation | 422 | Capture or refund exceeds what is allowed, or a live per-dispatch cap. |
capture_unsupported | 422 | Manual capture on a method that is sale-only. |
refund_exceeds_captured / refund_cap_exceeded | 422 / 429 | Refund limits. |
seller_not_found | 404 | |
beneficiary_fingerprint_conflict | 409 | The same account is already registered. |
cooling_off_active | 409 | The change's window has not elapsed or a notice is undelivered. |
approval_required | 409 | The action needs a second approver and cannot complete in this call. The success form of the same situation is a 202 with an approval_id in the body (payout approve and release, connection live requests). |
approver_must_differ | 422 | The requester tried to approve. |
approval_stale | 409 | The content changed since approval. |
step_up_required | 403 | A fresh second factor is needed. details.step_up.freshness_minutes. |
ato_session_blocked | 403 | Credentials changed in the last 24 hours. |
evidence_tier_insufficient | 422 | Fulfillment evidence too weak for this release. |
fulfillment_source_unknown / fulfillment_signature_invalid / fulfillment_event_replayed | 422 | Fulfillment ingestion refusals. |
policy_state_invalid | 409 | Wrong lifecycle state, replay required or stale, type mismatch. |
policy_validation_failed | 400 | The definition did not parse; findings in details. |
policy_not_published | 409 | |
webhook_signature_invalid | 400 | An inbound provider event failed verification. |
webhook_url_rejected | 422 | Not HTTPS on 443, or a private address. |
demo_rate_limited / demo_readonly_credential | 429 / 403 | Demo workspace limits. |
When the API itself rejects a request before a route runs: 400, 413, 415 and 422 map to validation_failed; 401 to unauthorized; 403 to forbidden; 404 to not_found; 409 to conflict; 429 to rate_limited.