# API error reference — Shorty API

> Every error the Shorty API can return, as RFC 9457 problem responses with a stable machine-readable code. Switch on the code, not the HTTP status.

Every error is an RFC 9457 `application/problem+json` body carrying a stable `code`. Switch on `code`, never on the human `title` or (alone) the HTTP status. Each code links to a page explaining when it happens and how to fix it.

| Code | HTTP | Meaning |
| --- | --- | --- |
| [`unauthorized`](/docs/api/errors/unauthorized) | 401 | Unauthorized |
| [`invalid_api_key`](/docs/api/errors/invalid_api_key) | 401 | Invalid API key |
| [`insufficient_scope`](/docs/api/errors/insufficient_scope) | 403 | Insufficient scope |
| [`feature_not_enabled`](/docs/api/errors/feature_not_enabled) | 403 | Feature not enabled |
| [`rate_limited`](/docs/api/errors/rate_limited) | 429 | Rate limit exceeded |
| [`quota_exhausted`](/docs/api/errors/quota_exhausted) | 429 | Quota exhausted |
| [`idempotency_conflict`](/docs/api/errors/idempotency_conflict) | 409 | Idempotency conflict |
| [`idempotency_key_reused`](/docs/api/errors/idempotency_key_reused) | 422 | Idempotency key reused |
| [`idempotency_in_progress`](/docs/api/errors/idempotency_in_progress) | 409 | Idempotency request in progress |
| [`resource_not_found`](/docs/api/errors/resource_not_found) | 404 | Resource not found |
| [`resource_not_ready`](/docs/api/errors/resource_not_ready) | 409 | Resource not ready |
| [`validation_failed`](/docs/api/errors/validation_failed) | 400 | Validation failed |
| [`request_too_large`](/docs/api/errors/request_too_large) | 413 | Request too large |
| [`unsupported_document_format`](/docs/api/errors/unsupported_document_format) | 422 | Unsupported document format |
| [`service_unavailable`](/docs/api/errors/service_unavailable) | 503 | Service unavailable |
| [`internal_error`](/docs/api/errors/internal_error) | 500 | Internal server error |