Errors

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.

{
  "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.
`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.

Get started

Core concepts

Guides

Error codes

​Error codes

Error codes