Errors
HTTP status codes, error shapes, and resilient client patterns.
Pipevideo returns conventional HTTP status codes with JSON error bodies.
Error shape
Failed requests return JSON:
{
"message": "Human readable error description"
}Rate-limited requests (429) may include additional data:
{
"message": "Rate limit exceeded. Please try again later.",
"data": {
"retry_after": 42
}
}Status codes
| Code | ORPC code | When | What to do |
|---|---|---|---|
| 400 | BAD_REQUEST | Invalid model, insufficient credits, malformed input, unsupported provider | Fix the request; retrying without changes will not succeed |
| 401 | UNAUTHORIZED | Missing, invalid, expired, or inactive API key | Check credentials; verify no whitespace in the key |
| 404 | NOT_FOUND | Generation not found (wrong id or different organization) | Verify the generation id |
| 429 | TOO_MANY_REQUESTS | Rate limit exceeded (100 req/min per key) | Wait retry_after seconds; see Rate limits |
| 500 | INTERNAL_SERVER_ERROR | Unexpected server error | Retry with exponential backoff |
Generation failures
When a generation's status is failed (via poll or webhook), check the error object or errorMessage:
| Cause | Description |
|---|---|
| Insufficient credits | Balance is zero or charge failed |
| Provider failure | Video orchestration provider or render pipeline error |
| Model not supported | Orchestration model not available on selected provider |
| Invalid prompt | Missing or empty text content |
Generation failures are distinct from HTTP errors — the POST may return 200 with status: "pending", and the failure appears on subsequent polls or via webhook.
Retry guidance
| Status | Retry? |
|---|---|
400 | No — fix the input |
401 | No — fix credentials |
404 | No — verify the resource id |
429 | Yes — after retry_after seconds |
500 | Yes — with exponential backoff and jitter |
For generation polling, continue polling on pending or processing. Stop on completed or failed.
Logging
Log status codes and error messages — never log raw API keys. Use generation id values to correlate with the dashboard and support requests.
Related
- Rate limits
- Video generation guide — generation-level error handling