ACCUZ® Brand Guard™ / SDK 1.3.3 / HTTP API v1

HTTP errors and verification results

Start here

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.

valid
Authenticity was accepted at decidedAt. Check current eligibility and show this operation’s count.
replay
This authenticated reading has already been consumed. Request a fresh physical tap.
invalid_signature
Authentication could not be confirmed. Show the failure without a product success badge.
unknown_tag
The tag could not be identified. Display the neutral result.
policy_rejected
The reading failed an acceptance policy. Preserve the recorded decision and do not count a success.

HTTP

HTTP 202 is pending. Respect Retry-After. Resume the same operation and retain the original key.

HTTPerror.codeAction
400invalid_idempotency_keySend exactly one Idempotency-Key header.
400invalid_bodyValidate JSON, encodingVersionId, tapUrl and optional fields against the request schema. The complete UTF-8 URL must fit 1024 bytes.
400invalid_encoding_versionConfirm the immutable encoding ID for the environment and selected connection with its administrator.
400invalid_tap_urlInspect the approved origin, exact NFC entry and encoding template. Capture the next tap before any rewrite.
401not_authorizedCheck the server secret, expiry, revocation and assigned API origin.
403not_authorizedCheck the scope granted for this API operation.
403integration_not_authorizedCheck tenant, connection, active credential and environment binding.
403execute_scope_requiredPOST requires verifications:execute.
403read_scope_requiredGET requires verifications:read. An execute-only caller can recover with the original POST.
404verification_not_foundCheck the receipt ID within the original integration.
409idempotency_conflictThe key is already bound to a different business request. Recover the original operation using its original request.
413body_too_largeLimit the JSON body to 4096 bytes.
415json_requiredUse Content-Type: application/json.
429rate_limitedRespect Retry-After and resume the same operation.
503operation_busyWait and retry the identical POST.
503retry_same_requestOutcome is uncertain. Preserve the original key, body and API origin.
503environment_unconfiguredContact the environment operator. Retry only the same pending operation once service recovers.

Reference server diagnostics

Use httpStatus, diagnosticCode and correlationId. A local 502 can report upstream httpStatus 200 when its complete body is invalid. Share the support reference only.

invalid_server_response / invalid_timestamp_response / invalid_seal_response / untrusted_identity_response / encoding_response_mismatch
Complete invalid HTTP 200: terminal unconfirmed; do not reverify.
verification_credential_rejected
HTTP 401: inspect the issued credential, environment, expiry and revocation.
verification_scope_or_origin_denied
HTTP 403: inspect connection, approved origin and granted scope.
verification_operation_conflict
HTTP 409: inspect the original key and business request.
token_required / credential_binding_missing_or_invalid
Local configuration failure before verification; supply the correct server secret binding.
response_read_interrupted_same_request
The complete body was not received. Recover using the original operation.