Errors and safe retries

Read error.retry

All current routes use the ErrorEnvelope contract. Check the error code and retry advice rather than guessing from the status alone. Retain x-request-id for support without logging credentials.

Recover the right way

Refresh an expired session; correct invalid input; review missing scopes. A not-found response may also protect an organisation boundary. Do not probe other organisations’ resource IDs.

Avoid duplicate writes

A timeout does not prove a write failed. Read the known resource’s state before retrying approval, key creation or refund requests. Never fall back to an older API automatically after an uncertain write.

Service failures

Handle unavailable services and incomplete results explicitly. Do not replace an error with an invented empty dataset or a zero balance.

Design useful error messages

Tell the user which action failed, whether the result is known and what can safely happen next. Invalid input needs a correction; unavailable services need an explicit unavailable state. Keep diagnostic identifiers for support, but exclude bearer tokens, API keys and raw private payloads from logs and screenshots.

Separate a retry from another execution

Reads can often be retried according to the returned advice, while an uncertain write needs a state check first. Bound automated attempts and keep the original request context. Never convert an exhausted retry into a fabricated success, zero cost or empty delivery.

Published error codes

These codes come from this OpenAPI snapshot. Use the returned error.status, error.retry and message together; a code alone does not authorise another execution.

• invalid_request
• invalid_json
• unauthenticated
• session_expired
• key_expired
• key_revoked
• credits_exhausted
• over_quote
• plan_required
• price_changed
• forbidden
• org_missing
• scope_missing
• not_entitled
• private_data
• access_control
• not_found
• quote_expired
• quote_already_approved
• refund_refused
• catalogue_refused
• not_for_sale
• export_not_ready
• download_expired
• idempotency_conflict
• stale_version
• package_not_ready
• upload_not_ready
• cost_changed
• billing_profile_missing
• export_not_available
• unknown_capability
• schema_retired
• payload_too_large
• unsupported_media_type
• rate_limited
• internal
• evidence_unavailable
• payment_provider_unavailable
• checkout_unavailable
• invoicing_unavailable
• unavailable

Published retry advice

The contract permits these values for error.retry:

• fix_request
• refresh_credentials
• never
• after_reset
• bounded