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

# Error handling

> Every error code the FlameProxies Customer API returns, the error response shape, and how to handle each one.

When a request fails, the Customer API returns a JSON body with a consistent shape.

## Error response shape

Every error has two fields:

```json theme={null}
{
  "error": "not_found",
  "message": "Human-readable error message."
}
```

| Field | Description |
| - | - |
| `error` | A machine-readable error code. Use this in your code to decide what to do. |
| `message` | A human-readable explanation. Log it, but don't parse it — the wording can change. |

## Error codes

| `error` | What it means | How to handle |
| - | - | - |
| `unauthorized` | The API key is missing, invalid, or revoked. | Don't retry. Check the `Authorization` or `x-api-key` header and the key's status in the dashboard. |
| `invalid_request` | A field is missing or has an invalid value. | Don't retry as-is. Read `message`, fix the request, then send it again. |
| `not_found` | The package doesn't exist or doesn't belong to your account. | Don't retry. Check the ID against [list packages](/api/packages/list). |
| `rate_limited` | You've made more than 120 requests in a minute with this key. | Wait, then retry with backoff. See [Rate limits](/api/rate-limits). |
| `unsupported_package` | The product or package isn't supported by the Customer API, which covers `residential` and `premium_residential` only. | Don't retry. Use a residential or premium residential package, or manage other products in the dashboard. |

## Handling errors in code

A pattern that covers the cases worth automating — retry `rate_limited` with backoff, and surface everything else:

<CodeGroup>
  ```python Python theme={null}
  import time
  import requests

  BASE_URL = "https://flameproxies.com/api/customer"

  def flame_request(method, path, *, api_key, max_attempts=5, **kwargs):
      headers = {"Authorization": f"Bearer {api_key}"}
      for attempt in range(max_attempts):
          resp = requests.request(method, f"{BASE_URL}{path}", headers=headers, **kwargs)
          if resp.ok:
              return resp.json()

          body = resp.json()
          if body.get("error") == "rate_limited":
              time.sleep(min(2 ** attempt, 60))  # exponential backoff, capped
              continue

          raise RuntimeError(f"FlameProxies API error {body.get('error')}: {body.get('message')}")
      raise RuntimeError(f"Gave up after {max_attempts} attempts: {path}")
  ```

  ```javascript Node.js theme={null}
  const BASE_URL = "https://flameproxies.com/api/customer";

  async function flameRequest(path, { apiKey, maxAttempts = 5, ...init } = {}) {
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
      const resp = await fetch(`${BASE_URL}${path}`, {
        ...init,
        headers: { Authorization: `Bearer ${apiKey}`, ...init.headers },
      });
      if (resp.ok) return resp.json();

      const body = await resp.json().catch(() => ({}));
      if (body.error === "rate_limited") {
        await new Promise((r) => setTimeout(r, Math.min(2 ** attempt * 1000, 60000)));
        continue;
      }

      throw new Error(`FlameProxies API error ${body.error}: ${body.message}`);
    }
    throw new Error(`Gave up after ${maxAttempts} attempts: ${path}`);
  }
  ```
</CodeGroup>

<Note>
  These are errors from the **Customer API** (`flameproxies.com/api/customer`). Problems with proxy traffic through `proxy.flameproxies.com` — such as `407 Proxy Authentication Required` — come from a different system. See [Connection debugging](/troubleshooting/connection-debugging).
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Rate limits" icon="gauge-high" href="/api/rate-limits">
    The per-key limit, and how to stay under it.
  </Card>

  <Card title="API authentication" icon="key" href="/api/authentication">
    Fix `unauthorized` errors.
  </Card>
</CardGroup>