Errors & troubleshooting
Handle a stable problem code, give users a useful next step, and retry only when appropriate.
On this page
A consistent problem response
The tenant API uses application/problem+json. Use code for application logic and requestId when contacting support. Do not branch on human-readable title text.
{
"type": "urn:wincora:problem:case-not-ready",
"title": "Case is not ready for submission",
"status": 409,
"code": "case_not_ready",
"requestId": "req_example",
"blockers": [{ "code": "document_missing" }]
}Choose the right recovery
| Status | Client action |
|---|---|
| 400 | Correct invalid input using the field or problem details. |
| 401 / 403 | Check the credential and grants. Do not repeatedly retry. |
| 404 | Check the resource mapping and permitted scope. |
| 409 | Resolve the business conflict, changed quote, or idempotency mismatch. |
| 410 | An event cursor has expired. Resynchronize. |
| 412 / 428 | Refresh the resource and send the required version. |
| 429 | Honor Retry-After and reduce concurrency. |
| 503 | Retry with backoff and the original idempotency key. |
Treat a lost response as uncertain
A disconnected request may already have committed. Recover with the same idempotency key or external reference rather than repeating it as a new action.
An upstream visa-query failure is an error response. It must not be presented as a successful determination that no authorization is required.
Send useful diagnostic context
Include the request ID, operation ID if present, approximate time, and the problem code. Exclude API keys, passport scans, raw personal data, and payment secrets.
Contact the integration team