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

# Errors

> Swippee's error envelope and the full error-code taxonomy.

Every error returns the same flat JSON envelope. **Branch on `error_code`, not the
HTTP status** — the status tells you the broad class, the code tells you exactly
what happened.

```json theme={null}
{
  "error_type": "RATE_LIMIT_ERROR",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "error_message": "Rate limit exceeded (60 requests/minute on the free plan).",
  "display_message": "You're going a little fast — try again in a moment.",
  "request_id": "req_8f3c9b2e4a1d4f7c9e0b1a2c3d4e5f60",
  "documentation_url": "https://docs.swippee.com/concepts/errors#rate_limit_exceeded",
  "suggested_action": "Slow down or upgrade your plan."
}
```

| Field               | Notes                                                                         |
| ------------------- | ----------------------------------------------------------------------------- |
| `error_type`        | Coarse grouping you can switch on (e.g. `AUTHENTICATION_ERROR`).              |
| `error_code`        | The specific, stable code. **This is what you branch on.**                    |
| `error_message`     | Developer-facing detail (may name plan limits, fields, etc.).                 |
| `display_message`   | Safe to show your end-user, or `null` when it isn't — never surface a `null`. |
| `request_id`        | Quote this when contacting support.                                           |
| `documentation_url` | Deep-link to this page for the code.                                          |
| `suggested_action`  | What to do next.                                                              |

## Error codes

| `error_code`                                                         | `error_type`          | HTTP | Meaning                                                                                            |
| -------------------------------------------------------------------- | --------------------- | ---- | -------------------------------------------------------------------------------------------------- |
| `MISSING_API_KEY`                                                    | AUTHENTICATION\_ERROR | 401  | No `Authorization` header sent.                                                                    |
| `INVALID_API_KEY`                                                    | AUTHENTICATION\_ERROR | 401  | Key does not exist.                                                                                |
| `REVOKED_API_KEY`                                                    | AUTHENTICATION\_ERROR | 401  | Key was revoked.                                                                                   |
| `INSUFFICIENT_SCOPE`                                                 | PERMISSION\_ERROR     | 403  | Key lacks the required scope (or org suspended).                                                   |
| `RATE_LIMIT_EXCEEDED`                                                | RATE\_LIMIT\_ERROR    | 429  | Per-org throughput cap hit. Honour `Retry-After`.                                                  |
| `QUOTA_EXCEEDED`                                                     | RATE\_LIMIT\_ERROR    | 429  | Monthly parse / data quota reached.                                                                |
| `INVALID_REQUEST`                                                    | INVALID\_REQUEST      | 400  | Request shape or parameters invalid.                                                               |
| `INVALID_FORMAT`                                                     | INVALID\_REQUEST      | 400  | Body malformed or not `multipart/form-data`.                                                       |
| `MISSING_FILE`                                                       | INVALID\_REQUEST      | 400  | Form field `file` is missing.                                                                      |
| `FILE_TOO_LARGE`                                                     | INVALID\_REQUEST      | 413  | File exceeds the 20 MB limit.                                                                      |
| `INVALID_RANGE`                                                      | INVALID\_REQUEST      | 400  | Requested date range is invalid.                                                                   |
| `IDEMPOTENCY_IN_PROGRESS`                                            | INVALID\_REQUEST      | 409  | Same `Idempotency-Key` still processing — retry shortly. See [Idempotency](/concepts/idempotency). |
| `IDEMPOTENCY_KEY_REUSED`                                             | INVALID\_REQUEST      | 422  | `Idempotency-Key` reused with different params. Use a fresh key.                                   |
| `UNSUPPORTED_DOCUMENT`                                               | DOCUMENT\_ERROR       | 422  | File is not a transaction statement.                                                               |
| `UNSUPPORTED_BANK`                                                   | DOCUMENT\_ERROR       | 422  | No supported Nepali bank detected.                                                                 |
| `IMAGE_STATEMENT_UNSUPPORTED`                                        | DOCUMENT\_ERROR       | 422  | Photo/scan — upload the original PDF.                                                              |
| `PASSWORD_REQUIRED`                                                  | DOCUMENT\_ERROR       | 422  | File is password-protected.                                                                        |
| `PASSWORD_INCORRECT`                                                 | DOCUMENT\_ERROR       | 422  | Supplied statement password was wrong.                                                             |
| `PARSE_FAILED`                                                       | DOCUMENT\_ERROR       | 422  | Bank detected but extraction failed.                                                               |
| `TAMPER_DETECTED`                                                    | FORENSICS\_ERROR      | 422  | Document shows signs of tampering.                                                                 |
| `IMAGE_NOT_TAMPER_VERIFIED`                                          | FORENSICS\_ERROR      | 422  | Images can't be tamper-verified — upload the PDF.                                                  |
| `FORENSICS_FAILED`                                                   | FORENSICS\_ERROR      | 500  | The forensics pass could not complete.                                                             |
| `NOT_FOUND`                                                          | NOT\_FOUND            | 404  | Resource not found on this organization.                                                           |
| `NOT_READY`                                                          | CONSENT\_ERROR        | 409  | Resource (report/consent) not ready yet.                                                           |
| `INVALID_CONSENT` / `CONSENT_INACTIVE`                               | CONSENT\_ERROR        | 403  | Consent missing or no longer active.                                                               |
| `GRANT_PENDING` / `GRANT_DENIED` / `GRANT_REVOKED` / `GRANT_EXPIRED` | CONSENT\_ERROR        | 403  | Vault access-grant state.                                                                          |
| `SOURCE_UNCONFIGURED` / `NO_DATA_YET` / `CURRENCY_NOT_PUBLISHED`     | DATA\_ERROR           | 404  | Data API: series/currency unavailable.                                                             |
| `INTERNAL_ERROR`                                                     | API\_ERROR            | 500  | Unexpected server error — retry with backoff.                                                      |