---
title: "API Errors and Retries - Documentation"
description: "Handle response envelopes, validation errors, rate limits, delivery failures, and retries without duplicating external actions."
canonical: "https://www.aifordatabase.com/docs/api-errors-and-retries/"
---

# API Errors and Retries

advanced 7 min read

## API Errors and Retries

Every v1 response uses the same envelope. Preserve `meta.requestId` in logs and support requests so a failed call can be traced.

### Error envelope

```json
{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "details": {}
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2026-08-04T10:00:00.000Z"
  }
}
```

### Important status codes

| Status | Meaning | Agent behavior |
| --- | --- | --- |
| 400 | Malformed body or invalid fields | Correct the request; do not retry unchanged |
| 401 | Missing, invalid, or expired key | Replace or rotate the API key |
| 403 | Missing scope or admin role | Request narrower, explicit authorization |
| 404 | Resource absent from this organization | Re-discover IDs; do not guess |
| 409 | Revision or resource conflict | Re-read current state before editing |
| 422 | Connection, preview, or delivery execution failed | Inspect `error.details` and attempts |
| 428 | Revision or delivery confirmation required | Supply the explicit precondition |
| 429 | Per-organization rate limit reached | Retry with exponential backoff and jitter |
| 500-599 | Unexpected or transient service error | Retry idempotent reads with backoff |

### Retry matrix

Generally safe to retry:

*   GET requests
*   Schema reads and workflow previews
*   Direct read-only SQL when duplicate execution is acceptable
*   429 and transient 5xx responses after backoff

Do not blindly retry:

*   `POST /api/v1/workflows/{id}/actions/{order}/test`
*   `POST /api/v1/workflows/{id}/run`
*   Webhook test deliveries
*   Credential rotation
*   Resource creation when the first response outcome is unknown

These calls may have completed even when the caller did not receive a successful response.

### External API acceptance

Webhook actions consider 2xx successful by default. Set `successStatusCodes` when a provider uses different 2xx codes for full and partial acceptance. For Brevo batch events, `[202]` treats HTTP 207 as a visible failure so partial acceptance is not reported as success.

### Pagination

List endpoints use `page` and `pageSize`. Continue until `page >= totalPages`. Do not assume cursor pagination.

### Rate limits

Rate limits are enforced per organization:

| Plan | General requests/min | Chat requests/min |
| --- | --- | --- |
| Free | 60 | 20 |
| Pro / Max | 300 | 100 |
| Enterprise | 1,000 | 500 |

Source: https://www.aifordatabase.com/docs/api-errors-and-retries/