Handle errors without repeating writes
Start with the HTTP status and error message. They tell you whether to fix the request, check permissions or try again. A failed connection does not prove that a write failed, so verify its outcome before repeating it.
- Keep the error detailsRecord the status, message and trace ID without secrets.
- Classify the failureSeparate invalid input, missing access, limits and temporary failures.
- Choose the appropriate actionCorrect the request, back off or inspect the write outcome.
- Verify the resultConfirm the operation’s state before continuing dependent work.
Read the complete response
HTTP errors do not all use one JSON envelope. Engine, management, compatibility adapters and gateways can return different fields or plain text. Check the HTTP status first, parse JSON only when appropriate, and retain the request ID from the response headers. An error may use code, error or class; do not assume a retry field exists.
For support, record the endpoint, time, status, SDK version and X-OC-Request-Id when present. Query execution may also provide X-OC-Query-Id. Remove tokens, database keys and private data before sharing logs.
Choose the next action
| Status | Likely cause | Action |
|---|---|---|
| 400 / 422 | Syntax, field, type, dimension or semantic validation | Read the returned detail and correct the request. |
| 401 / 403 | Authentication or permission failure | Check credential type, identity headers and grants. A new token does not grant additional permissions. |
| 404 | Wrong route or missing/hidden resource | Check host, tenant, table and key. Restricted objects may be hidden. |
| 409 | Conflict, duplicate key or transaction validation | Distinguish a permanent constraint violation from a concurrency conflict. Re-read and recompute before retrying a conflict. |
| 413 | Request or operation size limit | Split the work according to the endpoint’s batching contract. |
| 429 | Rate or capacity limit | Honor Retry-After when supplied; reduce concurrency. |
| 501 | Unsupported feature or deployment mode | Use a supported operation; repeating it unchanged will not enable support. |
| 500 / 502 / 503 / 504 | Server, gateway, capacity or timeout failure | Inspect the error and retry hint. Retry reads with bounded backoff; reconcile uncertain writes first. |
Retry only when safe
Check the retry behavior of your installed SDK. Do not automatically replay a write unless the endpoint explicitly supports deduplication for that operation. A new key on a later request does not identify it as the same operation, and an idempotency header alone does not make arbitrary SQL safe to repeat.
- For reads, use bounded exponential backoff with jitter and a total deadline when the failure is transient.
- Respect
Retry-Afterif provided. Do not use an unbounded retry loop. - For writes, check whether the route supports idempotency. Reuse the same key and payload for the same logical operation when supported.
- If the outcome of a write or
COMMITis unknown, read back or reconcile using an application key. Do not blindly rerun the transaction.
SQL clients
Wire clients also report SQLSTATE. Examples include 23505 for a unique constraint, 23503 for a foreign key, 42501 for insufficient privilege, 40001 for a transaction conflict and 0A000 for an unsupported feature. Use the returned code and message together; HTTP status numbers and SQLSTATE are different interfaces.
Find the relevant example
See error examples, limits, troubleshooting and transaction failure handling. Example response bodies illustrate that route; they are not a universal envelope for every endpoint.