Responses, errors & retries

AvraAPI returns a predictable JSON envelope. Handle the outer success value first, then process data or error.

Success envelope

{
  "success": true,
  "request_id": "2da44813-ec46-4dde-b403-6a371543e2b9",
  "data": {
    "example": "provider-specific result"
  }
}

Error envelope

{
  "success": false,
  "request_id": "2da44813-ec46-4dde-b403-6a371543e2b9",
  "error": {
    "code": "payment_configuration_not_available",
    "message": "No active payment method is configured for this project."
  },
  "meta": {
    "provider_override": null
  }
}

Common HTTP categories

Status	Meaning	Recommended handling
`401`	Credential missing, invalid, inactive, or bound to another environment	Stop and correct server credentials. Do not expose details to browser users.
`403`	Authenticated, but not authorized for the requested operation	Check scope, Workspace permissions, or plan entitlement.
`409`	Conflicting or already-running operation	Retry only after the documented short delay or after checking your own operation state.
`422`	Invalid request data or unavailable configuration	Correct the request or configuration; do not blind-retry.
`429`	Rate limit reached	Respect the retry window and apply backoff.
`502` / `503`	Provider or service problem	Use bounded retry with backoff when the operation is safe to repeat.

Idempotency and retries

For an operation that can create a charge, checkout, purchase, or other upstream side effect, use the documented idempotency mechanism when available. Reuse the same idempotency key only for the same intended operation. Never retry by generating a new order reference or changing a payment amount. For UPG checkout, retry at the backend only after deciding whether the previous create request could have reached the provider.

Request IDs

Persist the returned request_id in your own server-side log with your internal order or operation reference. Do not store customer secrets or provider callback bodies in that log.

Getting Started

Workspaces

Security & Integration

Documentation

Responses, errors & retries

Success envelope

Error envelope

Common HTTP categories

Idempotency and retries

Request IDs

​Success envelope

​Error envelope

​Common HTTP categories

​Idempotency and retries

​Request IDs

Success envelope

Error envelope

Common HTTP categories

Idempotency and retries

Request IDs