BY NUMBER7 AIDeveloper reference · v1
API errors and retry handling
Separate rejected requests, failed processing jobs and uploads whose acceptance is uncertain. Each needs a different next action.
Read the HTTP status and error code together.
{
"success": false,
"error": {
"code": "MISSING_FILE",
"message": "No document supplied",
"status": 400
}
}This is a request error. An asynchronous job can also finish with data.fileStatus: failed; inspect its documented failure information using the contract agreed for your account.
Choose the next action.
| Status / code | Next action |
|---|---|
400 · INVALID_DOCUMENT_TYPE / MISSING_FILE | Correct the document type or supply the file/URL. |
401 · UNAUTHORIZED | Check the Bearer token. |
403 · FORBIDDEN | Verify account access to the requested operation. |
404 · JOB_NOT_FOUND | Check the job ID and account context. |
413 · FILE_TOO_LARGE | Reduce the file to the documented upload limit. |
429 · RATE_LIMITED | Back off; respect Retry-After when returned. |
500 · INTERNAL_ERROR | Retry bounded reads with backoff; escalate repeated failures. |
Correct rejected requests Back off on rate limits Reconcile uncertain acceptance
A timeout can hide an accepted upload.
Reconcile before resubmission
Was the upload already accepted?
- You retained a job ID
- Look up that job and reconcile the existing result before submitting again.
- Acceptance is unknown
- Follow the agreed reconciliation/support process. Do not blindly repeat the upload.
Do not assume an idempotency header is supported unless it is part of your agreed API contract.
Bound retries and polling.
Use bounded exponential backoff with jitter for reads. Surface a timeout to the caller rather than polling forever, and retain the original source and any returned job ID for reconciliation.