Errors and idempotency

Attesso fails closed. A timeout, infrastructure failure, or non-allow response never grants permission to execute.

Problem responses

When Attesso supplies an error body, it uses application/problem+json. The values below illustrate the response shape; use the exact codes returned by the API.

{
  "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,
  "errors": [
    {
      "pointer": "/example/path",
      "code": "FIELD_ERROR_CODE",
      "message": "Human-readable field detail"
    }
  ]
}

Branch on the returned code, retryable, and field pointers. Do not branch on human-readable title, detail, or message text.

Status codes

Status	Meaning	Default handling
`400`	Malformed JSON or request syntax	Fix the request
`401`	Missing or invalid API key	Fix configuration; do not retry blindly
`404`	Resource not found in your organization	Verify the identifier and environment
`409`	Idempotency conflict or invalid state transition	Read current state and reconcile
`422`	Valid JSON that violates schema or domain limits	Fix the request
`429`	Rate limit exceeded	Back off; a response body is not guaranteed
`503`	Retryable infrastructure failure	Fail closed and retry with the same idempotency key

Edge-generated 429 responses may omit the problem body, request ID, and Retry-After header.

Idempotency keys

Every write requires Idempotency-Key.

Idempotency-Key: aut_01HZX8G2Q6V5

Keys must be 16–255 characters and contain only letters, digits, ., _, :, or -.

Scope one key to one logical operation.
Persist the key with your operation state before sending the request.
Retry identical canonical input with the same key.
Use a new key for a different operation.
Reusing a key with different input returns 409.

A successful replay returns the same resource identity in its current state and includes Idempotency-Replayed: true.

Retry pattern

Classify the failure

Respect retryable when a problem body is present. Treat uncertain execution outcomes as non-permission.

Keep the original operation identity

Reuse the same idempotency key and byte-equivalent logical input.

Back off with jitter

Honor Retry-After when present. Otherwise use bounded exponential backoff.

Reconcile by reading

If a lifecycle transition remains uncertain, retrieve the mandate or authorization before taking another action.

Log Attesso-Request-Id for correlation. It is safe to share with Attesso support and does not contain credentials.

Get started

Core concepts

Guides

Developer reference

Errors and idempotency

Problem responses

Status codes

Idempotency keys

Retry pattern

​Problem responses

​Status codes

​Idempotency keys

​Retry pattern

Problem responses

Status codes

Idempotency keys

Retry pattern