Errors

Canonical API error codes and response format

By YT2Text Team • Published February 1, 2025 • Updated February 23, 2026

Errors

Most 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

400/422: request/validation errors
401: missing/invalid key
403: permission denied
404: missing job/batch/resource
409: resource state invalid for requested action (for example result before completion)
429: throttled
500: unexpected internal failure