## Start with code, operation and environment

Documented error responses use a `detail` object containing `code` and `message`. Check the HTTP status too. Do not treat an error JSON response as a successfully created transaction.

| Code | Recommended check |
| --- | --- |
| `validation_error` | Required fields, types, country, locale and contract bounds |
| `invalid_api_key` | Credential, revocation and environment |
| `tenant_environment_disabled` | Tenant and environment enablement |
| `transaction_not_found` | Correct identifier, Tenant and environment |
| `idempotency_conflict` | Same key used with a different payload |
| `tenant_ip_not_authorized` | Authorized egress IP for the operation |
| `api_key_scope_not_allowed` | Key permissions for the resource |

## Separate connection failures from contract denials

A lost creation response leaves an uncertain result. Use the same idempotency key and payload according to the [idempotency guide](/en/developers/kyc/idempotency). Deterministic credential, scope or payload errors need correction; unlimited retries only conceal the cause.

For temporary unavailability, configure timeouts and a bounded retry policy in your client. Do not assume an availability promise or a universal attempt limit.

## Share useful diagnostics

Record the time, environment, method, path without secrets, HTTP status and sanitized error code. Include the transaction identifier in a support request when available. Remove API keys, webhook secrets, personal data and journey links. Compare your request with the [reference](/en/developers/kyc/reference) and [examples](/en/developers/kyc/examples-and-downloads) before changing business behavior.