Errors and idempotency

Attesso uses application/problem+json when it supplies an error body.

{
  "type": "https://example.invalid/problem-type",
  "title": "Human-readable summary",
  "status": 422,
  "code": "MACHINE_READABLE_CODE",
  "detail": "Human-readable detail",
  "request_id": "req_01J2ABCDEF",
  "retryable": false
}

Branch on code and retryable. The API does not send field-level pointers; detail names the rule that failed, so fix the request from it. Do not branch on human-readable text.

Status handling

Status	Meaning	Default handling
`400`	Malformed request syntax	Fix the request
`401`	Missing or invalid API key	Fix configuration
`404`	Resource unavailable in this organization	Verify ID and environment
`409`	Idempotency conflict or invalid transition	Read and reconcile state
`422`	Valid JSON violates schema or domain rules	Fix the request
`429`	Rate limited	Back off; a body is not guaranteed
`503`	Retryable infrastructure failure	Fail closed and retry safely

Authorization decisions

An authorization is a durable record, not an HTTP error. A refusal is 201 with decision: "DENY", state: "DENIED", and can_execute: false. Never execute on DENY or INDETERMINATE.

`reason.code`	Decision	Meaning
`POLICY_MATCH`	`ALLOW`	Every constraint matched; one reservation was created
`POLICY_MISMATCH`	`DENY`	A present value failed a constraint; `violations` names the path and code
`PERIOD_LIMIT_EXCEEDED`	`DENY`	The recurring period budget would be exceeded
`MANDATE_NOT_ACTIVE`	`DENY`	The Mandate is not `ACTIVE`, for example `SCHEDULED`
`MANDATE_UNAVAILABLE`	`DENY`	Another reservation is in flight, or the Mandate cannot evaluate
`MANDATE_TERMINAL`	`DENY`	The Mandate is `CONSUMED`, `REVOKED`, or `EXPIRED`
`OUTSIDE_VALIDITY_WINDOW`	`DENY`	The proposed execution is outside the Mandate window
`TERMS_CHANGED`	`DENY`	The approved terms no longer match
`REQUIRED_ATTRIBUTE_MISSING`, `ATTRIBUTE_TYPE_MISMATCH`, `UNSUPPORTED_ATTRIBUTE`, `UNSUPPORTED_POLICY_VERSION`	`INDETERMINATE`	The action could not be evaluated

reason.violations[] carries path, code, and, when the failing check has them, observed and bound. path is a JSON Pointer: /attributes/section, /payment/amount. Policy constraints name the same paths as attributes.section and payment.amount. Violation codes are ACTION_MISMATCH, VALUE_MISMATCH, VALUE_NOT_ALLOWED, ABOVE_MAXIMUM, OUTSIDE_DATE_RANGE, REQUIRED_ATTRIBUTE_MISSING, and ATTRIBUTE_TYPE_MISMATCH. violations is present for POLICY_MISMATCH and for decisions of INDETERMINATE. State refusals carry code only. PERIOD_LIMIT_EXCEEDED carries code and message.

Idempotency keys

Every write except external reports requires Idempotency-Key; a report replays by its external_reference. Keys contain 16 to 255 letters, digits, periods, underscores, colons, or hyphens.

Persist one key before sending each logical operation.
Retry that operation with the same key and identical logical input.
Use a new key for a new operation.
Reusing a key with different input returns 409.
A successful replay returns the same resource identity in its current state.

Recover a lost create response

If a create response was lost, find the Mandate by its external_reference:

GET /v1/mandates?external_reference=booking-91823&limit=20
Authorization: Bearer att_test_...

The match is exact, newest first. limit is 1 to 100 (default 20). has_more is true when more Mandates carry the same reference; raise limit to read them. The result is scoped to the calling Organization. There is no unfiltered list and no cursor. If more than 100 Mandates share the reference, only the newest 100 are returned. Unknown query parameters are refused with 422.

Retry pattern

Treat every timeout or unavailable response as non-permission.
Keep the original operation identity and input.
Back off with jitter and honor Retry-After when present.
Read the Mandate or Authorization before starting any replacement action.

Log the safe Attesso-Request-Id for support correlation. Never log API keys, identity assertions, approval URLs, or external credentials.

Start

Core model

Integration guides

Bounds

PSP integrations

Reference

Errors and idempotency

Status handling

Authorization decisions

Idempotency keys

Recover a lost create response

Retry pattern

​Status handling

​Authorization decisions

​Idempotency keys

​Recover a lost create response

​Retry pattern

Status handling

Authorization decisions

Idempotency keys

Recover a lost create response

Retry pattern