API errors
Read the HTTP status and response body, identify the cause, and decide what to fix before retrying.
Read the HTTP status and the response body together. The status identifies the kind of failure; the body may explain which input, permission or resource caused it.
- Read the HTTP statusDistinguish rejected input from access or service failures.
- Inspect the responseFind the field, permission or resource involved.
- Decide the next actionFix the cause; verify uncertain writes before retrying.
- 2xx: Read the result.
202can acknowledge work that is still running. For a partial-write207, inspect bothinsertedanderror. - 4xx: Check the request or access. For
429, honorRetry-After. - 5xx: Check the outcome before retrying a write; it may already have applied.
Read the error body
The error value can be a message string or an object.
Optional fields vary by route; do not assume a universal error code.
Synthetic examples show the envelope, not guaranteed error messages or class names.
{
"error": "Example invalid request",
"class": "example_error_class"
}Find the status code
Each endpoint lists its own documented status codes.
| Status | What to do |
|---|---|
| 400 | Correct the request before retrying. |
| 401 | Check the credential and Authorization header. |
| 402 | Check feature access or available credits. |
| 403 | Check tenant access, roles and permissions. |
| 404 | Check the resource ID and API route. |
| 408 | Reduce query work or adjust the timeout. |
| 409 | Resolve the conflict before retrying. |
| 412 | Refresh the version or ETag before writing again. |
| 413 | Split or reduce the request body. |
| 415 | Send the required Content-Type. |
| 422 | Correct the values or unsupported combination. |
| 429 | Honor Retry-After when present; back off. |
| 499 | The client cancelled the request. |
| 500 | Check the outcome before retrying a write. |
| 501 | Check deployment support for this operation. |
| 502 | Check service availability and the write outcome. |
| 503 | Honor Retry-After when present; check write outcomes. |
{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The requested resource was not found."
}Check the resource ID and API route.
{
"error": "The request exceeded its time limit."
}Reduce query work or adjust the timeout.
{
"error": "The request conflicts with the current resource state."
}Resolve the conflict before retrying.
{
"error": "precondition_failed"
}The If-Match precondition required an existing row.
Refresh the version or ETag before writing again.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "The request Content-Type is not supported."
}Send the required Content-Type.
{
"error": "The supplied values cannot be processed."
}Correct the values or unsupported combination.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The client cancelled the request."
}The client cancelled the request.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "This operation is not supported by this deployment."
}Check deployment support for this operation.
{
"error": "An upstream service returned an invalid response."
}Check service availability and the write outcome.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
Handle errors in your application
Parse the body safely and preserve the HTTP status.
Do not retry writes automatically. Check the endpoint's retry contract and whether the first request already changed data.
// Node.js 20+ · handle both error shapes and empty responses.
const response = await fetch(url, options);
const text = await response.text();
let body;
try { body = text ? JSON.parse(text) : null; }
catch { body = text; }
if (!response.ok) {
const error = body && typeof body === 'object' ? body.error : body;
const message = typeof error === 'string'
? error : error?.message ?? 'Request failed';
console.error(response.status, message);
// Retry only when the operation and outcome make it safe.
throw new Error(message);
}
if (response.status === 207) {
// Partial NDJSON write: inspect inserted and error; committed rows remain.
console.log(body);
} else {
console.log(body);
}