Five authenticity decisions can arrive in HTTP 200. Validate the entire envelope before displaying a decision. A complete malformed 200 ends locally as unconfirmed with a support reference. If the server sends an HTTP error, use the status and stable code below. A gateway may omit the JSON body.
HTTP 202 is pending. Respect Retry-After. Resume the same operation and retain the original key.
| HTTP | error.code | Action |
|---|
| 400 | invalid_idempotency_key | Send exactly one Idempotency-Key header. |
| 400 | invalid_body | Validate JSON, encodingVersionId, tapUrl and optional fields against the request schema. The complete UTF-8 URL must fit 1024 bytes. |
| 400 | invalid_encoding_version | Confirm the immutable encoding ID for the environment and selected connection with its administrator. |
| 400 | invalid_tap_url | Inspect the approved origin, exact NFC entry and encoding template. Capture the next tap before any rewrite. |
| 401 | not_authorized | Check the server secret, expiry, revocation and assigned API origin. |
| 403 | not_authorized | Check the scope granted for this API operation. |
| 403 | integration_not_authorized | Check tenant, connection, active credential and environment binding. |
| 403 | execute_scope_required | POST requires verifications:execute. |
| 403 | read_scope_required | GET requires verifications:read. An execute-only caller can recover with the original POST. |
| 404 | verification_not_found | Check the receipt ID within the original integration. |
| 409 | idempotency_conflict | The key is already bound to a different business request. Recover the original operation using its original request. |
| 413 | body_too_large | Limit the JSON body to 4096 bytes. |
| 415 | json_required | Use Content-Type: application/json. |
| 429 | rate_limited | Respect Retry-After and resume the same operation. |
| 503 | operation_busy | Wait and retry the identical POST. |
| 503 | retry_same_request | Outcome is uncertain. Preserve the original key, body and API origin. |
| 503 | environment_unconfigured | Contact the environment operator. Retry only the same pending operation once service recovers. |
Use httpStatus, diagnosticCode and correlationId. A local 502 can report upstream httpStatus 200 when its complete body is invalid. Share the support reference only.