One JSON shape on every failure. The status code tells you what happened; message tells you why.
Every error is a JSON object with one error key. Nothing else is at the top level: no separate status or success field to check.
{
"error": {
"code": 404,
"message": "Not found",
"detail": "Not found"
}
}Response fields
error.codenumbererror.messagestringerror.detailstringCheck the HTTP status first. It groups failures the way your retry logic should: 4xx is on the request, 5xx is on Dyva.
Bad request
The request body or a parameter failed a check. message names the specific problem.
Unauthorized
Missing, malformed, or expired credentials.
Payment required
The action needs an active subscription or balance you do not currently have.
Forbidden
Valid credentials, not enough permission. Wrong key scope, or account restricted.
Not found
The resource does not exist, or does not belong to you.
Conflict
The action collides with existing state, for example a duplicate.
Validation error
The request was understood but cannot be processed as sent.
Too many requests
Rate limit or daily message cap hit. See Rate Limits.
Internal server error
Something broke on Dyva's side. Safe to retry.
Bad gateway
An upstream provider failed. Safe to retry with backoff.
Service unavailable
Temporarily down, for example during a deploy or dependency outage. Safe to retry with backoff.
Switch on error.code, not the message text. message is written for a person reading it, not for a switch statement, and its exact wording isn't a stable contract.
async function dyvaFetch(url, options = {}) {
const res = await fetch(url, {
...options,
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
...options.headers,
},
});
if (!res.ok) {
const { error } = await res.json();
if (error.code === 401) {
await refreshToken();
return dyvaFetch(url, options);
}
if (error.code === 429 || error.code === 502 || error.code === 503) {
await new Promise((r) => setTimeout(r, 2000));
return dyvaFetch(url, options);
}
throw new Error(`[${error.code}] ${error.message}`);
}
return res.json();
}The most common failures, and the fix for each.
401429502