Responses and errors
Vudy API responses use a JSON envelope. Check the HTTP status and success, and use error.code for programmatic error handling.
Success#
{
"success": true,
"data": {}
}HTTP status is typically 200 or 201 depending on the endpoint.
Error#
{
"success": false,
"error": {
"code": "SERVER_VALIDATION_API_AUTH_02",
"message": "Human-readable explanation",
"details": {}
}
}| Field | Meaning |
|---|---|
error.code | Machine-readable identifier, such as SERVER_VALIDATION_API_AUTH_02 |
error.message | Human-readable summary; wording can change |
error.details | Optional structured context; shape depends on the error |
Current error codes use uppercase underscore-separated identifiers ending in a two-digit number. Treat the complete value as opaque: do not construct codes or infer behavior from individual segments. For example, API-key limits return SERVER_VALIDATION_API_AUTH_12 (hourly) or SERVER_VALIDATION_API_AUTH_19 (burst).
Common HTTP statuses#
| Status | When |
|---|---|
| 200 / 201 | Success |
| 400 | Invalid body, query, or request-specific validation |
| 401 | Missing/invalid required session or unresolved conditional context |
| 403 | API-key authentication, permission, or route-level access failure |
| 404 | Resource not found |
| 409 | Conflict |
| 429 | API-key hourly or burst limit exceeded |
| 500 | Unexpected server failure |
| 503 | A required platform access gate is closed |
Useful response headers#
| Header | Meaning |
|---|---|
x-trace-id | Request correlation ID to include in support requests |
RateLimit-Limit | Limit for the window represented by the response |
RateLimit-Remaining | Remaining requests in that window |
RateLimit-Reset | Seconds until that window resets |
RateLimit-Policy | Hourly and per-second policies, for example 1000;w=3600, 100;w=1 |
Retry-After | Whole seconds to wait; present when a rate limit blocks a request |
Handling errors in JavaScript#
async function callVudy(path, options = {}) {
const res = await fetch(`https://api-stg.vudy.app${path}`, {
...options,
headers: {
"x-api-key": process.env.VUDY_API_KEY,
"Content-Type": "application/json",
...(options.headers || {}),
},
});
const body = await res.json();
if (!res.ok || !body.success) {
const err = new Error(body.error?.message || "Vudy API error");
err.code = body.error?.code;
err.details = body.error?.details;
err.status = res.status;
err.traceId = res.headers.get("x-trace-id");
throw err;
}
return body.data;
}Do not retry a failed mutation unless its endpoint contract documents safe retry or idempotency behavior. For 429, wait for Retry-After; for 503, check platform maintenance status before retrying.