# Error Handling

### Error response format

```json
{
  "code": "validation_error",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "destinationCurrency",
      "message": "Must be one of: NGN, KES, USD, EUR, GBP"
    }
  ]
}
```

### HTTP status codes

<table><thead><tr><th width="148">Status</th><th width="214">Meaning</th><th>Common causes</th></tr></thead><tbody><tr><td>200</td><td>OK</td><td>Request succeeded</td></tr><tr><td>201</td><td>Created</td><td>Resource created successfully</td></tr><tr><td>400</td><td>Bad Request</td><td>Invalid request body or parameters</td></tr><tr><td>401</td><td>Unauthorised</td><td>Missing or invalid <code>x-api-key</code> header</td></tr><tr><td>403</td><td>Forbidden</td><td>Key lacks required scope, IP not in allowlist, or country restricted</td></tr><tr><td>404</td><td>Not Found</td><td>Resource does not exist</td></tr><tr><td>409</td><td>Conflict</td><td>Idempotency key used with different request body</td></tr><tr><td>422</td><td>Unprocessable</td><td>Business logic error (expired quote, recipient not approved)</td></tr><tr><td>429</td><td>Rate Limited</td><td>Too many requests</td></tr><tr><td>500</td><td>Server Error</td><td>Internal error — contact support</td></tr><tr><td>503</td><td>Service Unavailable</td><td>API temporarily down</td></tr></tbody></table>

### Error codes

<table><thead><tr><th width="314">Code</th><th>Description</th></tr></thead><tbody><tr><td><code>validation_error</code></td><td>Request failed validation — check <code>details</code> array</td></tr><tr><td><code>unauthorized</code></td><td>Invalid or missing API key</td></tr><tr><td><code>forbidden</code></td><td>API key lacks required scope</td></tr><tr><td><code>not_found</code></td><td>Resource does not exist</td></tr><tr><td><code>quote_expired</code></td><td>Quote has expired — request a new one</td></tr><tr><td><code>recipient_not_approved</code></td><td>Recipient has not passed KYC</td></tr><tr><td><code>duplicate_request</code></td><td>Idempotency key reused with different body</td></tr><tr><td><code>rate_limit_exceeded</code></td><td>Too many requests — wait and retry</td></tr><tr><td><code>internal_error</code></td><td>Unexpected server error</td></tr></tbody></table>

### Handling errors in your application

```javascript
const response = await fetch('/api/v1/off-ramp', { ... });

if (!response.ok) {
  const error = await response.json();
  
  switch (error.code) {
    case 'quote_expired':
      // Request a new quote and retry
      break;
    case 'recipient_not_approved':
      // Check recipient KYC status
      break;
    case 'rate_limit_exceeded':
      // Wait for Retry-After duration
      const retryAfter = response.headers.get('Retry-After');
      break;
    default:
      console.error('Zynta API error:', error);
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zynta.com/guides/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.