# Errors and retries

Handle invalid requests, scope conflicts and uncertain delivery results.

## HTTP status handling

| Status | Recommended handling |
|---|---|
| 400 | Correct request syntax and required fields |
| 401 / 403 | Check session, permission, scope, CSRF and same-origin requirements |
| 404 | Check identity and availability in the selected institution |
| 409 | Resolve the reported revision, scope or evidence-state conflict |
| 413 | Compare payload size with the permitted limit |
| 429 / 503 | Inspect the response and Retry-After when present; use bounded backoff |

Not every endpoint returns every status. Before recording an error body, ensure it contains no credentials or unnecessary personal information.

## Optimistic concurrency

Definition updates use the relevant expectedRevision or expectedVersion. On a conflict, fetch the current definition and reconsider the change rather than repeating the stale value indefinitely. Do not continue in a stale screen scope after scope_changed.

## Safe retries

Preserve documented idempotent operation identities for identical content. A comparison runId must not be reused for a different request. SDK custody receipts use a separate protocol from portal operations. An uncertain network outcome is not proof of success.