Unif API DocsErrors
Every error UnifAPI returns to agents and HTTP clients, what it means, and how to recover.
Errors always come back in the same envelope, regardless of which public-data operation was called:
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.typeis from a closed vocabulary (see table below) — stable, machine-readable, safe for agents and clients to switch on.error.messageis for humans and may change without notice.error.request_idis the UnifAPI trace id. Include it in support requests.error.issuesis present only whentype = validation_error— it's the raw Zod issue list.
The HTTP status mirrors the type — clients can pick whichever signal they prefer.
Reference
| Status | type | When it happens | Recovery |
|---|---|---|---|
| 400 | validation_error | Request failed gateway-side validation (bad query, missing body field). | Inspect error.issues. Fix the request. |
| 400 | invalid_id | The provided id was syntactically valid but not accepted by the public source. | Use a real id. |
| 401 | unauthorized | OAuth or API-key credentials are missing, malformed, revoked, or disabled. | Re-authenticate or rotate the key. |
| 404 | not_found | The resource (video, user, room, ...) does not exist, is deleted, or is private. | Confirm the id; some resources are private and 404 by design. |
| 429 | rate_limited | Workspace or source rate limit exceeded. | Honor Retry-After. See Rate limits. |
| 500 | internal_error | UnifAPI itself failed (uncaught exception). | Safe to retry. Report request_id if it persists. |
| 500 | response_shape_error | Source data no longer matches the published schema. | Report request_id — drift is a bug. |
| 502 | upstream_error | A public-data source returned an error UnifAPI cannot recover from. | Inspect error.message. |
| 503 | upstream_unavailable | A public-data source timed out or is unreachable. | Retry with exponential backoff. |
The table above is the public contract for the current error vocabulary.
Anatomy of a validation error
For validation_error, the issues array carries the raw Zod issue list so an agent or caller can map errors back to fields:
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}Always log request_id
Every error response carries request_id when UnifAPI can attach one. Log it and include it in support requests; it is the fastest way to debug a failed Skill run or HTTP call.