Errors

Canonical API error codes and response format

By YT2Text Team • Published February 1, 2025 • Updated March 22, 2026

Errors

Many route-level business failures use a stable envelope:

{
  "success": false,
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "Feature unavailable on current plan",
    "details": {}
  }
}

Common error codes

```
INVALID_REQUEST
```
– malformed payload or validation error
```
UNAUTHORIZED
```
– missing/invalid credentials
```
INVALID_KEY
```
/
```
INVALID_API_KEY
```
/
```
KEY_NOT_FOUND
```
– key does not exist, malformed, or revoked
```
FORBIDDEN
```
– authenticated user lacks permission for this route
```
RATE_LIMIT_EXCEEDED
```
– too many requests in current window
```
QUOTA_EXCEEDED
```
– daily/plan quota is exhausted
```
FEATURE_NOT_AVAILABLE
```
– feature blocked for plan
```
JOB_NOT_FOUND
```
– unknown job id
```
JOB_NOT_COMPLETED
```
– result not ready yet
```
JOB_FAILED
```
– job failed after processing
```
BATCH_NOT_FOUND
```
– unknown batch id
```
LIMITS_ERROR
```
– internal usage/limit accounting failure
```
LIST_ERROR
```
– list/filter retrieval failure
```
RESULTS_ERROR
```
– unable to assemble result payload

HTTP status mapping

Do not assume every failure maps cleanly to an HTTP status. The current backend mixes two patterns:

application/business-rule failures often return
```
success: false
```
via the JSON envelope
auth, CSRF/origin, and throttling failures are commonly raised as real HTTP errors
400/422: request/validation errors
401: missing or invalid auth credentials
403: permission denied, invalid origin, CSRF failure, or runtime-disabled feature
404: missing job/batch/resource on routes that raise
```
HTTPException
```
429: throttled API-key request
500: unexpected internal failure

Examples of envelope-style failures that may still arrive with HTTP 200 today:

```
FEATURE_NOT_AVAILABLE
```
```
QUOTA_EXCEEDED
```
```
JOB_NOT_FOUND
```
```
JOB_NOT_COMPLETED
```