# Errors

> Every code the API can answer with, what it means and what to do.

Source: https://docs.nocamclub.com/errors

There are two places an error can appear. Neither one costs credits.

## Refused at once

The call answers with an HTTP error, and nothing started:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "gpt-image-2 doesn't support aspect ratio 5:4.",
    "path": "input.aspect_ratio",
    "hint": "Use one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9.",
    "retryable": false,
    "request_id": "req_01a1b37b65dc7dcd8c060f296add5cf8",
    "docs_url": "https://docs.nocamclub.com/errors/invalid_parameter"
  }
}
```

| Field | What it is |
|---|---|
| `code` | Stable, safe to write code against |
| `message` | What happened, for people and agents |
| `path` | The field at fault |
| `hint` | What to do about it |
| `retryable` | Whether the same request can work, after any wait the error names |
| `request_id` | Quote this if you contact us |
| `docs_url` | A page about this code |

Some codes add fields, such as `credits`, `balance` and `top_up_url` on `insufficient_credits`, or `limit` on `rate_limited`.

| Code | HTTP | Meaning | Worth retrying? |
|---|---|---|---|
| [`invalid_request`](https://docs.nocamclub.com/errors/invalid_request.md) | 400 | The request can't be read | After a change |
| [`invalid_parameter`](https://docs.nocamclub.com/errors/invalid_parameter.md) | 400 | A field is wrong | After a change |
| [`unknown_model`](https://docs.nocamclub.com/errors/unknown_model.md) | 400 | That model isn't on sale | After a change |
| [`input_refused`](https://docs.nocamclub.com/errors/input_refused.md) | 400 | Refused by content rules | After a change |
| [`invalid_api_key`](https://docs.nocamclub.com/errors/invalid_api_key.md) | 401 | The key isn't valid | No |
| [`expired_api_key`](https://docs.nocamclub.com/errors/expired_api_key.md) | 401 | The key has expired | No |
| [`insufficient_credits`](https://docs.nocamclub.com/errors/insufficient_credits.md) | 402 | Not enough credits | No |
| [`account_suspended`](https://docs.nocamclub.com/errors/account_suspended.md) | 403 | The account is paused | No |
| [`ip_not_allowed`](https://docs.nocamclub.com/errors/ip_not_allowed.md) | 403 | Not from this address | No |
| [`missing_scope`](https://docs.nocamclub.com/errors/missing_scope.md) | 403 | The key can't do this | No |
| [`model_not_allowed`](https://docs.nocamclub.com/errors/model_not_allowed.md) | 403 | The key can't use this model | No |
| [`origin_not_allowed`](https://docs.nocamclub.com/errors/origin_not_allowed.md) | 403 | Not from this page | After a change |
| [`spend_limit_reached`](https://docs.nocamclub.com/errors/spend_limit_reached.md) | 403 | A spend limit is reached | No |
| [`not_found`](https://docs.nocamclub.com/errors/not_found.md) | 404 | Not found | After a change |
| [`idempotency_conflict`](https://docs.nocamclub.com/errors/idempotency_conflict.md) | 409 | This key was used with another request | After a change |
| [`no_route`](https://docs.nocamclub.com/errors/no_route.md) | 409 | No route can do this right now | After a change |
| [`not_cancelable`](https://docs.nocamclub.com/errors/not_cancelable.md) | 409 | Too late to cancel | After a change |
| [`not_finished`](https://docs.nocamclub.com/errors/not_finished.md) | 409 | Still in progress | Yes |
| [`not_for_sale`](https://docs.nocamclub.com/errors/not_for_sale.md) | 409 | Not on sale with these settings | After a change |
| [`upload_not_found`](https://docs.nocamclub.com/errors/upload_not_found.md) | 409 | The file isn't there yet | Yes |
| [`file_too_large`](https://docs.nocamclub.com/errors/file_too_large.md) | 413 | The file is too big | After a change |
| [`unsupported_media`](https://docs.nocamclub.com/errors/unsupported_media.md) | 415 | We can't read this file | After a change |
| [`rate_limited`](https://docs.nocamclub.com/errors/rate_limited.md) | 429 | Too many requests | Yes |
| [`too_many_active`](https://docs.nocamclub.com/errors/too_many_active.md) | 429 | Too many in progress | Yes |
| [`internal`](https://docs.nocamclub.com/errors/internal.md) | 500 | Something went wrong on our side | Yes |
| [`platform_paused`](https://docs.nocamclub.com/errors/platform_paused.md) | 503 | The API is paused | Yes |

## On a failed generation

The call was accepted, and later the generation ended with `status: "failed"`. The credits are already back.

```json
{
  "status": "failed",
  "price": {
    "credits": 4,
    "usd": "0.04",
    "charged": false
  },
  "error": {
    "code": "content_refused",
    "message": "The model refused this request under its content rules. Your credits came back. Change the prompt or the files before trying again.",
    "hint": "Change the prompt or the files. Trying the same again can't help, and refusals count toward a pause of the account.",
    "retryable": false,
    "docs_url": "https://docs.nocamclub.com/errors/content_refused"
  }
}
```

It has the same `hint` and `retryable` as a refused call. To try again, send the same request with a new `Idempotency-Key`.

| Code | Meaning | Worth retrying? |
|---|---|---|
| [`content_refused`](https://docs.nocamclub.com/errors/content_refused.md) | The model or our check refused it | After a change |
| [`bad_input_file`](https://docs.nocamclub.com/errors/bad_input_file.md) | The model couldn't read a file | After a change |
| [`unsupported_request`](https://docs.nocamclub.com/errors/unsupported_request.md) | The model can't do this combination | After a change |
| [`prompt_too_long`](https://docs.nocamclub.com/errors/prompt_too_long.md) | The prompt is too long | After a change |
| [`output_limit`](https://docs.nocamclub.com/errors/output_limit.md) | The answer didn't fit | After a change |
| [`timed_out`](https://docs.nocamclub.com/errors/timed_out.md) | The model didn't finish in time | Yes |
| [`provider_unavailable`](https://docs.nocamclub.com/errors/provider_unavailable.md) | No route could run it | Yes |
| [`generation_failed`](https://docs.nocamclub.com/errors/generation_failed.md) | The generation failed | Yes |
| [`sandbox_failure`](https://docs.nocamclub.com/errors/sandbox_failure.md) | The sandbox failed it on request | After a change |
| [`canceled`](https://docs.nocamclub.com/errors/canceled.md) | Canceled | After a change |

[`input_refused`](https://docs.nocamclub.com/errors/input_refused.md) can also arrive here, when a model refuses one of your files after the start.

Retrying a failed generation needs a **new** `Idempotency-Key`: the old one returns the same failure.