> ## 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.