Error Codes

All API errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "status": 400,
    "details": {}
  }
}

HTTP Status Codes

Status	Meaning
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request -- invalid parameters
401	Unauthorized -- invalid or missing authentication
403	Forbidden -- insufficient permissions
404	Not Found -- resource does not exist
409	Conflict -- resource already exists or state conflict
413	Payload Too Large -- file exceeds maximum size
422	Unprocessable Entity -- validation error
429	Too Many Requests -- rate limited
500	Internal Server Error
503	Service Unavailable -- temporarily down

Application Error Codes

Authentication Errors

Code	Description
UNAUTHORIZED	Missing or invalid API key / JWT
TOKEN_EXPIRED	JWT has expired
KEY_REVOKED	API key has been revoked
INSUFFICIENT_SCOPE	Key does not have required permissions

Validation Errors

Code	Description
INVALID_PARAMS	Request body failed validation
INVALID_FORMAT	Unsupported audio format
INVALID_URL	Source URL is not reachable
DURATION_TOO_SHORT	Segment duration below minimum (1 second)
DURATION_TOO_LONG	Segment duration exceeds source length

Job Errors

Code	Description
JOB_NOT_FOUND	Job ID does not exist
JOB_ALREADY_PROCESSING	Job cannot be modified while processing
JOB_FAILED	Processing failed (check error.details)
DOWNLOAD_EXPIRED	Segment download URL has expired

Billing Errors

Code	Description
QUOTA_EXCEEDED	Monthly quota reached with no overage
PAYMENT_REQUIRED	Account has unpaid invoices
PLAN_NOT_FOUND	Invalid plan ID
ALREADY_SUBSCRIBED	Active subscription exists

File Errors

Code	Description
FILE_TOO_LARGE	File exceeds plan's max file size
UNSUPPORTED_FORMAT	Audio format not supported
CORRUPT_FILE	File could not be decoded
DOWNLOAD_FAILED	Could not download from source URL

Error Details

Some errors include a details object with additional context:

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Validation failed",
    "status": 422,
    "details": {
      "fields": [
        {
          "field": "segmentDuration",
          "message": "Must be a positive integer"
        },
        {
          "field": "outputFormat",
          "message": "Must be one of: mp3, wav, flac, ogg, aac"
        }
      ]
    }
  }
}