Errors and recovery
On this page
Handle failures without guessing whether a write completed.
Keep safe support context
Keep the safe requestId or X-Request-Id for support, together with the operation and time. Keep credentials, applicant data and document URLs out of logs.
Respond to HTTP failures
| Response | Next action |
|---|---|
| 400 / 422 | Correct the request using the operation's schema and error code; do not retry unchanged invalid input. |
| 401 | Stop and ask the administrator to check the missing, invalid, expired or revoked key. |
| 403 | Check the required permission and company scope. Do not automatically request broader access. |
| 404 | Check the returned resource ID and task. Another company's resource is not made accessible by changing an ID. |
| 409 | Read the error code and current resource/preview/form version. Resolve the conflict before another mutation. |
| 410 | Follow the operation's meaning: an expired sync cursor requires a new full sync; a removed application must not be recreated by an old retry. |
| 429 | Honor Retry-After when supplied and X-RateLimit-Reset; apply bounded backoff with jitter. |
| Timeout / temporary 5xx | Treat a write outcome as unknown. Use known-ID readback or the original-key replay within the 24-hour window, with bounded backoff. Do not create a fresh operation. |
Recover an unknown write outcome
After a lost response, read the resource or operation back if its returned ID is known. If no returned ID is known, retry the identical request with the original Idempotency-Key and original API key within 24 hours of the first attempt. If that window has elapsed or safe readback/replay is unavailable, stop and reconcile the outcome; neither reusing an expired key nor choosing a fresh key guarantees that a write will not run again. Import previews, jobs and their history remain bound to the key that created them.
Rotate and retire credentials
For rotation, create a replacement key with the same or narrower permissions, deploy it to the integration and verify an authenticated read. Before revoking the old key, finish or reconcile its outstanding previews and jobs using the old key. A replacement key does not inherit their job IDs or history. Then revoke the old key. The administrator uses Settings → API & agents or its authenticated /api/v1/settings/api-keys control plane. A company integration key is not an administrator session. Key IDs are non-secret references, not credentials; the raw key cannot be retrieved later. Verify that the retired key is rejected.
Use the published contract version
Use the API version and lifecycle shown in the API reference, the schemas for each operation, and any required form or resource version when updating an integration. Preserve opaque versions unchanged and pin an approved MCP release. Event names come from the same catalog as the API; arrival order and a product version are not substitutes for current resource readback.