Keep a stable intent
Plan creation, operation submission and consumer receipts require an idempotency key. Send Idempotency-Key or idempotency_key in JSON; the header takes precedence. Keys are bounded to 128 characters. Use one stable key per intent, not a new key for every network retry.
With the same actor, organization and endpoint scope, a matching request can replay the recorded result. Reusing a key for a different intent returns 409 idempotency_conflict. Choose a new key only for a deliberate new intent. These guarantees do not automatically apply to other writes, including resource registration and operation controls.
Interpret errors
v1 handler errors use { "error": { "code": "…", "message": "…" } }. Use error.code for decisions; do not parse human-readable messages.
| Status | What to check |
|---|---|
| 400 / 413 / 415 | Request shape, body size or media type. Fix the request; do not blindly retry. |
| 401 / 403 | Session, token, scopes, organization and exact workload binding. More retries do not grant access. |
| 404 | Use an ID visible to the intended organization. Do not probe other tenants. |
| 409 | Read the code: changed intent, stale plan, unregistered consumer or a lifecycle conflict require different corrections. |
| 429 | Exchange/introspection rate limiting. Honor Retry-After before retrying. |
Not every endpoint returns every status. See each OpenAPI operation for its contract. Middleware or infrastructure may reject a request before the v1 handler, so also handle non-JSON failures safely.
Retry safely
- For timeouts, first inspect any known operation ID. If retrying an idempotent request, keep its actor, body and key unchanged.
- Use bounded backoff for transient failures. Do not loop indefinitely or silently obtain broader scopes.
- After a 202 response, inspect operation state and consumer evidence instead of resubmitting as though execution failed.
Log status, a safe request correlation and operation ID—not bearer headers, exchange bodies or private material.