Error Codes

All errors return a non-2xx HTTP status and a JSON body:

1 {
2   "detail": {
3     "code": "COLLECTION_NOT_FOUND",
4     "message": "Collection not found"
5   }
6 }

The code field is stable and machine-readable. The message field is human-readable and may change.

HTTP status codes

Code	HTTP	Description
`UNAUTHORIZED`	401	API key missing or invalid
`INVALID_API_KEY`	401	The provided API key does not exist or has been revoked
`SESSION_EXPIRED`	401	Session token has expired
`FORBIDDEN`	403	The key exists but doesn’t have permission for this action

Code	HTTP	Description
`COLLECTION_NOT_FOUND`	404	Collection ID not found, or not owned by this account
`COLLECTION_NAME_TAKEN`	409	A collection with this name already exists in your account

Code	HTTP	Description
`VIDEO_NOT_FOUND`	404	Video ID not found, or not owned by this account

Code	HTTP	Description
`UPLOAD_TOO_LARGE`	413	File exceeds the 5 GB maximum
`UNSUPPORTED_FORMAT`	415	File type is not supported. Accepted: MP4, MOV, AVI, WebM, MPEG, MKV
`PLAN_LIMIT_EXCEEDED`	402	Upload would exceed your plan’s storage limit

Code	HTTP	Description
`SEARCH_LIMIT_EXCEEDED`	402	Daily search quota exhausted (Free plan)
`SEARCH_UNAVAILABLE`	503	Search service temporarily unavailable — retry shortly

Code	HTTP	Description
`INSUFFICIENT_CREDITS`	402	Account has no remaining credits
`PAYMENT_METHOD_REQUIRED`	402	Action requires a saved payment method
`PAYMENT_FAILED`	402	Stripe payment attempt failed
`BILLING_NOT_CONFIGURED`	402	No billing account associated with this user

Code	HTTP	Description
`JOB_NOT_FOUND`	404	Job ID not found or not owned by this account

Code	HTTP	Description
`API_KEY_NOT_FOUND`	404	API key ID not found
`API_KEY_ALREADY_REVOKED`	409	Key has already been revoked
`API_KEY_LIMIT_REACHED`	402	Account has reached the maximum number of API keys for this plan

Code	HTTP	Description
`VALIDATION_ERROR`	422	Request parameter failed validation — check the `message` field
`NOT_FOUND`	404	Generic not found
`INTERNAL_ERROR`	500	Unexpected server error
`RATE_LIMIT_EXCEEDED`	429	Too many requests — retry with exponential backoff