---
title: API errors and error codes
sidebar_label: Errors
sidebar_position: 6
description: Every ElectroSwap API error is JSON with a stable code. The full status and code table, which errors charge credits, and the two worth handling first.
keywords: [api errors, error codes, insufficient_credits, http status, error handling]
---

# Errors

Every error is JSON:

```json
{ "error": { "code": "insufficient_credits", "message": "Not enough credits. Nothing was executed and nothing was charged." } }
```

Match on `code`. The `message` is for a human and may be reworded; the code will
not change without a version bump.

| Status | `code` | What happened | Charged? |
| --- | --- | --- | --- |
| 400 | `invalid_request` | Malformed parameter. | **No** |
| 400 | `invalid_limit` | `limit` above the maximum for that route. | **No** |
| 401 | `missing_key` | No `Authorization` header. | No |
| 401 | `invalid_key` | Not a key we recognise. | No |
| 401 | `unknown_key` | A key we could not load. Rare, and a retry usually resolves it to one of the two above. | No |
| 401 | `key_revoked` | You revoked it. | No |
| 402 | `insufficient_credits` | Not enough credits. **Nothing was executed.** | **No** |
| 403 | `key_suspended` | Suspended after repeated refused requests. | No |
| 404 | `not_found` | No such token, collection or presale. | **No** |
| 429 | `rate_limited` | Too many requests a second. | No |
| 429 | `too_many_concurrent` | Too many requests in flight at once. | No |
| 429 | `cost_ceiling` | This key spent its per-minute credit budget. | No |
| 503 | `server_busy` | We are shedding load, or a [heavy route](./rate-limits.md#heavy-routes) has both its slots in use. | **No** |
| 503 | `service_disabled` | The public API is switched off. | No |
| 500 | `server_error` | Our fault. | **No** |

## The two that matter

**`402 insufficient_credits` means nothing ran.** The check happens before the
query, not after it — you have not been charged, and you have not received a
partial answer. The body tells you your balance and where to top up.

**A `429` sets `Retry-After`.** Honour it. Repeatedly ignoring a 429 will
auto-suspend the key for fifteen minutes; we suspend the key rather than banning
your IP address, because a ban would take out everyone behind your egress and a
browser challenge is not something an API client can solve.

## What we never do to a valid key

We do not IP-ban you and we do not serve you a browser challenge. If you hold a
valid key, the worst outcome is a 429 or a temporary suspension of that key.