> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses, errors & retries

> Use AvraAPI response envelopes, request IDs, error codes, idempotency, and safe retry behavior.

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

## Success envelope

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

## Error envelope

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.