Errors
Error format and status codes
Errors come back with an appropriate HTTP status code and a JSON body:
{
"error": "Unauthorized",
"status": 401,
"timestamp": "2026-07-10 08:39:57.287380Z"
}Some endpoints include additional context (for example a message or field-level details on validation errors). The shape above is the guaranteed baseline.
Status codes
| Code | Meaning | Typical cause |
|---|---|---|
200 | OK | |
201 | Created | Resource created (e.g. viewer, post) |
400 | Bad Request | Malformed JSON or invalid parameters |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Key is valid but not allowed to do this |
404 | Not Found | Wrong ID, or the resource isn't visible to the API (e.g. a private video) |
422 | Unprocessable Entity | Validation failed: check the response body |
429 | Too Many Requests | Slow down; retry with backoff |
5xx | Server error | Rare; safe to retry with backoff |
Handling errors well
- Retry
429and5xxwith exponential backoff; treat4xx(except429) as bugs to fix, not transient failures. - Don't parse error strings: branch on the status code.
- A
404on a video you know exists usually means it's private or the ID belongs to another channel.
The SDK throws typed errors carrying the status code, so you can handle these cases without touching raw responses.