Error codes
This page is the single source of truth for error handling. SDK-specific error codes are documented in each SDK's Error handling page; this page covers errors at the API contract level.
HTTP status codes
| Code | Meaning |
|---|---|
200 OK | Request succeeded. |
400 Bad Request | Payload is malformed or required fields are missing. The body identifies the problematic fields. |
401 Unauthorized | Authentication missing, expired, or invalid. |
403 Forbidden | Authentication is valid but the tenant is not enabled for the requested resource (e.g., calling a capability not in your APIKEY). |
404 Not Found | Resource does not exist or does not belong to the authenticated tenant. |
409 Conflict | The resource exists but is not in the right state for this operation (e.g., fetching documents from a process still in progress). |
410 Gone | The resource existed but was deleted per the retention policy (document fetch endpoints), or the process exists but ended in an error state — see Get Process. |
429 Too Many Requests | You hit the rate limit. Retry with exponential backoff. |
5xx | Platform error. Retry with backoff; if persistent, contact support with the response body and timestamp. |
Retry policy
| Status | Should retry? | How |
|---|---|---|
5xx | Yes | Exponential backoff (1s, 2s, 4s, 8s, …). Cap at 5 attempts. |
429 | Yes | Honor the Retry-After header if present; otherwise exponential backoff. |
4xx (other) | No | The request is wrong. Fix the input before retrying. |
401 | Conditionally | Refresh the access token once. If the new request also returns 401, the issue is structural — don't retry. |
The IDCloud platform does not currently expose an idempotency-key mechanism on creation endpoints. Be cautious when retrying Create Process — a network error on a 5xx may have actually succeeded server-side, and a retry would create a duplicate process. When in doubt, retrieve recent processes by your internal correlation ID before retrying.
Where SDK errors live
The error catalogs of the Android SDK, iOS SDK, and Flutter SDK are documented in each SDK's dedicated Error handling page:
These cover device-side errors (camera permission denied, capture timeout, network unreachable on the device) — separate from the API-side errors documented here.