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

# Errors and retries

> The error shape, every code, and which ones are safe to retry.

Every error has the same shape:

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "The balance is $0.005. This needs $0.013.",
    "details": null,
    "requestId": "req_0193f2a7b8c77d1e9f3a4b5c6d7e8f90"
  }
}
```

* **`code`**: act on it. It stays stable.
* **`message`**: for people. It can change. Do not parse it.
* **`details`**: more facts for some codes, or `null`.
* **`requestId`**: quote it when you write to [support](mailto:support@apiforgeo.com).

## Codes

| Status | `code` | What to do | Retry? |
| - | - | - | - |
| 400 | `invalid_request` | Fix the request. `details` names the field. | No |
| 400 | `model_not_available` | Pick a model from `GET /v1/models` that runs in that country. | No |
| 400 | `webhook_url_invalid` | Use a valid `https` URL. | No |
| 401 | `unauthenticated` | Send a valid key. It may be revoked, or an old secret after a rotation. | No |
| 402 | `insufficient_balance` | Top up the balance. | After a top-up |
| 403 | `key_budget_exceeded` | Raise the key's budget, or use another key. | After a change |
| 403 | `organization_suspended` | Contact support. | No |
| 403 | `forbidden` | The key cannot do this. | No |
| 404 | `not_found` | Check the id. A task is visible only to its organization. | No |
| 409 | `idempotency_key_reused` | The key went with another body. Use a new `Idempotency-Key`. | No |
| 409 | `conflict` | The resource is not in a state that allows this. | No |
| 429 | `rate_limited` | Slow down. | Yes, with backoff |
| 500 | `internal_error` | Our fault. Quote `requestId` if it persists. | Yes, with backoff |
| 503 | `provider_unavailable` | A service behind the API does not answer. | Yes, in a minute |

## Retry safely

Retry only `429`, `500`, `503` and network errors. Wait longer each time, for example 1, 2, 4, 8 and 16 seconds.

A `POST /v1/tasks` that timed out may have created the task. Always send an `Idempotency-Key` on it. A retry with the same key and body then returns the first task, and charges once. See [Retry safely](https://docs.apiforgeo.com/concepts/tasks.md#retry-safely-with-an-idempotency-key).

A `GET` is always safe to retry.

## A task that fails

A task can fail after it was created. Its `status` is then `failed`, `error` has a `code` and a `message`, and a live task is refunded.

| `error.code` | Meaning |
| - | - |
| `run_failed` | The model run failed. |
| `provider_unavailable` | The model did not take the task after several attempts. |
| `provider_refused` | The model refused the task. |

A failed task does not run again. To try again, create a new task.


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