Errors, Limits and Troubleshooting
What each API error means and what to do about it.
How errors look
Every error comes back as JSON with an error object holding a code and a human-readable message. Build your handling on the code; the message may be reworded over time. Some errors also include extra fields, such as retry_after (seconds to wait) or, for insufficient_credits, your balance and the amount required.
Error codes
| HTTP | Code | What it means | What to do |
|---|---|---|---|
| 400 | invalid_request | Something in the request is not allowed: a length outside the range, an unknown mode or ratio, a bad seed, a page size or starting_after that is not valid, or JSON that does not parse. | Read the message. It names the field and the allowed values. |
| 401 | invalid_api_key | The key is missing, badly formatted, unknown or revoked. | Check the Authorization header is "Bearer " plus your full key. Create a new key if it was revoked. |
| 402 | insufficient_credits | Your balance is lower than this render costs. Nothing was charged. | Buy credits on /developer, or turn on auto-recharge. |
| 403 | api_access_disabled | API access is not switched on for this account. | Request access through /support. |
| 404 | not_found | No such video or webhook endpoint on your account. | Check the id. Videos are deleted after 7 days. |
| 409 | not_ready | The video has no file to download yet. | Check its status and wait for "done". |
| 409 | already_rendering | You tried to cancel a video that has started rendering. | Wait for it to finish, then delete it if needed. |
| 409 | endpoint_disabled | You sent a test event to a switched-off webhook endpoint. | Fix the cause, then turn it back on from /developer. |
| 429 | rate_limited | Too many requests in a short time. | Slow down. Wait for retry_after seconds if it is given, then retry. |
| 429 | concurrency_limit | You already have 5 renders queued or rendering on this key. | Wait for one to finish before starting another. |
| 503 | capacity | The render queue is full for the moment. | Retry in a few minutes, waiting longer after each try. |
| 503 | unavailable | A temporary problem on our side. | Retry shortly. Nothing was charged for a render that was not accepted. |
Limits to plan around
Each key can have at most 5 renders in flight (queued or rendering) at once. There are also limits on how fast you can send requests. When you hit one you get a 429 with retry_after; wait that long and try again.
For steady volume, keep a queue on your side and start a new render when a webhook tells you one has finished.
Tip
- Retrying a create request after a network error? Send an Idempotency-Key header with a unique value per video. If the first attempt did get through, the retry returns the original response instead of charging you twice.
- Use exponential backoff for 429 and 503 errors: wait longer after each failed try.
Common problems
| Problem | Likely cause and fix |
|---|---|
| /developer says API access is invite-only | Access is not on for your account yet. Buy credits on that page and it turns on by itself, or press Request API Access. |
| Buy panel asks you to accept a watermark | Your account has no paid Studio plan, so cloud renders carry the ballengine.app watermark. Tick the box to buy anyway, or pick a plan for watermark-free videos. |
| Credits bought but balance unchanged | Wait a few seconds; the page checks again automatically. If they have not appeared after about half a minute, contact support. |
| Balance on /developer is lower than in the Studio | The Studio figure can include a plan's monthly allowance, which the API cannot spend. /developer shows bought credits only. |
| Webhook never arrives | Press Send test and read the result. Check the address is public https, your server answers 2xx within 10 seconds, and the endpoint is not switched off. |
| All my endpoints were switched off at once | Test or resend requests kept coming after the rate limit. Stop the script sending them, then turn the endpoints back on from /developer. |
| Webhook signature does not match | Hash the raw body, not re-serialised JSON, and use the current signing secret. |
| The video looks different from last time | Each request is randomized. Reuse the seed from the version you liked. |
Tip
- For anything else, contact support at /support and include the video id or the time of the request. Never send us your full API key.
More from BallEngine
Guides, plans and answers for making your videos.