Errors
The error format, and how to handle each kind of failure.
Errors use RFC 9457 application/problem+json. Branch on code, never on title or detail, which can change.
422 Unprocessable Content
{
"type": "https://docs.vojo-media.com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"detail": "1 field failed validation.",
"instance": "/v1/screens",
"code": "validation_failed",
"request_id": "req_7f3a9c2e41b84d0f",
"errors": [{ "pointer": "/name", "code": "required", "detail": "name is required" }]
}Each type URL opens that code's page here. When you contact support, quote request_id, which is also in the Vojo-Request-Id response header.
What to do
| Status | What it means | What to do |
|---|---|---|
| 400 | The JSON, a query value or a cursor is malformed. An unsupported sort returns 422 instead. |
Fix the request. |
| 401 | The credential is missing, invalid, expired or revoked. | Check your key. |
| 402 | A plan limit or storage quota blocks the request. | Read feature_key, limit and used. |
| 403 | The key lacks a scope, or the organisation header doesn't match it. | Add the scope or fix the header. |
| 404 | The resource doesn't exist, or it belongs to another organisation. | Check the id. |
| 409 | A conflict with existing state, or an Idempotency-Key problem. |
See Idempotency. |
| 422 | One or more fields failed validation. | Read errors[]: one entry per field, each with a JSON Pointer. |
| 429 | You're over a rate limit. | Wait Retry-After seconds, then retry. |
| 500 | Something failed on Vojo's side. | Reads are safe to retry. Retry creates with the same Idempotency-Key. |
The error codes page lists every code. New codes can be added within /v1, so treat a code you don't recognise by its HTTP status.