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

# Errors

> HTTP status codes returned by the API.

The native API uses conventional HTTP status codes to signal success and failure.

| Status | When                                                                      |
| ------ | ------------------------------------------------------------------------- |
| `401`  | Missing, invalid, or inactive API key.                                    |
| `402`  | Insufficient funds to reserve the job's price.                            |
| `403`  | API key lacks permission for the requested model.                         |
| `404`  | `GET /jobs/{job_id}` for an unknown id or a job owned by another account. |
| `422`  | Validation failure — unfetchable URL or oversized input.                  |
| `502`  | Upstream storage failure while ingesting inputs.                          |
| `503`  | The project or the requested model is paused — try again later.           |

## Handling tips

<AccordionGroup>
  <Accordion title="401 — Authentication">
    Verify the `Authorization: Bearer <key>` header and that the key is active. See [Authentication](/authentication).
  </Accordion>

  <Accordion title="402 — Insufficient funds">
    Check [`GET /balance`](/api-reference/get-balance). The `available` amount must cover the job's reserved price.
  </Accordion>

  <Accordion title="403 — Model permission">
    The key isn't scoped for the requested model. Grant access in the web panel or use a different key.
  </Accordion>

  <Accordion title="422 — Validation">
    Common causes: an `input_images_urls` entry that can't be fetched, total input size over 200 MB, or an `aspect_ratio` the model doesn't support.
  </Accordion>

  <Accordion title="503 — Paused">
    Transient — the project or model is paused. Retry later, ideally with the same [`Idempotency-Key`](/authentication#idempotency).
  </Accordion>
</AccordionGroup>

## Gemini-compatible API

The [Gemini-compatible endpoint](/gemini/overview) returns errors in Google's envelope so the `google-genai` SDK surfaces them as `errors.APIError`:

```json theme={null}
{
  "error": {
    "code": 403,
    "message": "API key missing permission for gemini-3-pro-image",
    "status": "PERMISSION_DENIED"
  }
}
```

| HTTP  | `status`            | When                                                                                        |
| ----- | ------------------- | ------------------------------------------------------------------------------------------- |
| `400` | `INVALID_ARGUMENT`  | Invalid API key, malformed request, unsupported `imageSize`, or a request body over 200 MB. |
| `403` | `PERMISSION_DENIED` | Missing API key, or the key lacks permission for the model.                                 |
| `404` | `NOT_FOUND`         | Unknown model id.                                                                           |
| `503` | `UNAVAILABLE`       | Project or model paused, or no capacity — retry later.                                      |
| `504` | `DEADLINE_EXCEEDED` | The upstream request timed out.                                                             |
| `500` | `INTERNAL`          | Unexpected server error.                                                                    |

<Note>
  A prompt blocked for safety is **not** an error: it returns `200` with `finishReason: IMAGE_SAFETY` and no image, and is not charged.
</Note>