Status Codes

Top-level HTTP errors

A request rejected before a successful endpoint response uses the Kratos error envelope below.

{
  "code": 503,
  "reason": "PROVIDER_UPSTREAM_UNAVAILABLE",
  "message": "the selected provider is unreachable; retry later",
  "metadata": {}
}

reason is the stable machine-readable value. Branch on it.
code is the HTTP status repeated in the JSON body.
message is a human-readable explanation and is not a stable branch key.
metadata contains only fields explicitly allowed for that reason, such as batch maxSize.

Outward reason catalog

Each operation documents only the reasons its request path can produce. Reasons not approved at the gateway boundary are folded into GATEWAY_PROVIDER_UNAVAILABLE.

HTTP	`reason`	What happened	What to do
400	`GATEWAY_MALFORMED_BODY`	The request body does not match this endpoint's schema. Unknown fields, misspelled names, wrong casing, and wrong types are rejected before screening.	Fix the body against the endpoint schema. Do not branch on message text; it is written for people and may change.
400	`PROVIDER_INVALID_ADDRESS`	The address is not valid on the chain named in the request body.	Correct the address or chain, then send a new request.
400	`PROVIDER_UNSUPPORTED_CHAIN`	The selected provider does not serve this chain for the requested capability.	Call List capability chains for the provider and capability, then choose one of the returned chains or select another enabled provider.
400	`PROVIDER_UNSUPPORTED_TRANSACTION`	The selected provider rejected this transaction for the requested chain, direction, output address, or asset.	Correct the transaction request. Repeating it unchanged will not help.
400	`PROVIDER_INVALID_TRANSACTION`	The transaction hash is not valid on the chain named in the request.	Correct the hash or chain, then send a new request.
400	`PROVIDER_INVALID_REQUEST`	The platform rejected the request before a provider call because a required field is missing or a value is invalid.	Correct the request using the endpoint schema. Repeating it unchanged will not help.
400	`PROVIDER_INVALID_PAGE_TOKEN`	The cursor is invalid. Cursors are opaque and must come from a previous nextCursor response.	Start without cursor, then return each nextCursor unchanged as the next request's cursor.
400	`PROVIDER_BATCH_INVALID`	The address batch is empty or absent; proto3 cannot distinguish those two forms.	Submit at least one address.
400	`BATCH_SIZE_EXCEEDS_PROVIDER_LIMIT`	The batch exceeds the selected provider's per-request limit. Error metadata carries provider, requested, and maxSize.	Split the request into batches no larger than maxSize. List enabled providers returns the same batch.maxSize before submission.
400	`PROVIDER_CAPABILITY_UNSUPPORTED`	The selected provider does not offer the capability required by this endpoint.	Select an enabled provider that advertises the capability, or omit provider to use the tenant default. The API returns an error rather than an empty result.
400	`TENANT_VENDOR_NOT_BOUND`	The request names a provider that is not enabled for this tenant. The platform does not silently fall back to the default.	Use a provider returned by List enabled providers, or omit provider to use the tenant default.
401	`GATEWAY_CREDENTIAL_INVALID`	The request did not pass API-credential authentication.	Check the Authorization header and credential before retrying.
404	`PROVIDER_NOT_FOUND`	The provider slug is not registered on this platform.	Use a slug returned by List enabled providers.
404	`SANDBOX_ADDRESS_NOT_FOUND`	No recorded sandbox response matches this provider, capability, chain, subject, and request shape.	Use a subject from the supplied sandbox catalog or a live credential. Repeating the same sandbox request will return the same error.
404	`PROVIDER_TRANSACTION_NOT_FOUND`	The hash is well formed, but no transaction was found on the requested chain.	Retry if the transaction is still pending; otherwise verify that the hash belongs to the selected chain.
404	`SCREENING_JOB_NOT_FOUND`	The batch job does not exist or does not belong to this tenant. Those states are deliberately indistinguishable.	Use the jobId returned by Submit address batch and the credential that created it.
409	`TENANT_NO_VENDOR_BINDING`	No provider is enabled for this tenant, so no provider call was made.	Contact support to enable a provider for the tenant.
409	`PLATFORM_DEFAULT_VENDOR_MISSING`	The tenant has no provider binding and the platform has no default from which to create one.	Contact support; changing the request cannot repair platform configuration.
409	`TENANT_VENDOR_BINDING_INVALID`	The tenant's enabled providers do not contain exactly one default, so the platform refuses to choose arbitrarily.	Contact support to repair the tenant-provider binding.
429	`GATEWAY_QUOTA_BALANCE_EXHAUSTED`	Your organisation has spent its cumulative screening quota, which every API key shares. No clock refills it.	Ask your account manager to add quota. Retrying does not help until they do.
429	`PROVIDER_RATE_LIMITED`	The selected provider rate-limited the upstream call. This is separate from your screening quota.	Retry with backoff or select another enabled provider.
501	`GATEWAY_ENDPOINT_NOT_IMPLEMENTED`	The published endpoint is not currently implemented by the upstream service.	Do not retry unchanged; use another available endpoint or contact support.
502	`GATEWAY_PROVIDER_UNAVAILABLE`	The gateway could not obtain an outward-safe authoritative response from the provider service.	Retry later. Do not treat this response as a clean screening result.
502	`PROVIDER_MALFORMED_RESPONSE`	The selected provider answered, but the platform could not normalize the response into the published contract.	Retry once; if it repeats, report the trace id. Do not interpret it as no risk found.
503	`TENANT_VENDOR_UNAVAILABLE`	The explicitly selected provider, or the tenant default when provider was omitted, is unavailable to this request. Its provider row may be missing or disabled, or no adapter may be registered.	Select another enabled provider. If none is available, contact support to repair provider or tenant-binding configuration.
503	`PROVIDER_UPSTREAM_UNAVAILABLE`	The selected provider was unreachable or timed out before returning a usable response.	Retry with backoff or select another enabled provider. No conclusion was established.
503	`PROVIDER_DISABLED`	The selected provider is disabled or has no usable integration configuration.	Select another enabled provider or contact support.
503	`GATEWAY_ACCOUNT_UNAVAILABLE`	The gateway could not verify the credential with the account service and rejected the request.	Retry later; do not replace the credential based on this response alone.
503	`GATEWAY_QUOTA_UNAVAILABLE`	The gateway could not confirm the quota deduction, so it did not screen. Nothing was charged that it can see.	Retry later. A retry may succeed; it will not be charged twice for the same attempt.

Status codes do not replace reason

Different reasons can share one HTTP status but require different action.

A 503 can mean a selected provider is temporarily unavailable or that tenant-provider configuration needs repair; inspect reason before retrying.
A 502 means the gateway or provider could not produce an outward-safe normalized response. It is not a low-risk result.
A 409 represents tenant/provider configuration state, not a malformed screening body.
GATEWAY_QUOTA_BALANCE_EXHAUSTED is your organisation's cumulative screening quota, shared by every API key; PROVIDER_RATE_LIMITED is the selected provider's upstream limit.

Branch on reason, then use metadata only for keys documented for that reason.

Batch acceptance and item failures

Submit address batch returns 202 Accepted. Invalid or duplicate addresses rejected before acceptance appear in rejected; accepted addresses run asynchronously.

An accepted item can later fail with ScreeningJobResult.error.reason, a closed enum with no diagnostic-text field. progress.total is accepted addresses, done is successful terminal items, and failed is failed terminal items. A job is terminal when done + failed == total.

Batch item error reasons

These enum values appear inside ScreeningJobResult.error.reason after a batch was accepted. They are not top-level HTTP reasons and carry no diagnostic-text field.

Item reason	What happened	What to do
`SCREENING_JOB_ITEM_ERROR_REASON_UNSPECIFIED`	Reserved protobuf zero value. A conforming failed item does not emit it.	Treat it as a malformed response and contact support. Do not infer whether retrying or changing input will help.
`SCREENING_JOB_ITEM_ERROR_REASON_UPSTREAM`	The provider call for the batch leg was unreachable, timed out, or rate-limited.	Retry the batch with backoff, or select another enabled provider that offers address batch.
`SCREENING_JOB_ITEM_ERROR_REASON_SANDBOX_NOT_FOUND`	The complete sandbox request and ordered address combination has no recording.	Use an exact recorded combination. Repeating the unchanged request cannot succeed.
`SCREENING_JOB_ITEM_ERROR_REASON_VENDOR_ITEM`	The provider explicitly marked this accepted address as failed.	Do not treat it as clean. Review the address and selected provider; retrying unchanged is not guaranteed to help.
`SCREENING_JOB_ITEM_ERROR_REASON_VENDOR_NO_ANSWER`	The provider batch response omitted this accepted address.	Resubmit the missing address. If the provider omits it again, contact support with the jobId.
`SCREENING_JOB_ITEM_ERROR_REASON_PLATFORM`	The platform could not normalize or attribute the provider result for this address.	Retry once. If it repeats, contact support with the jobId; do not interpret it as a clean result.
`SCREENING_JOB_ITEM_ERROR_REASON_EXECUTOR`	The batch executor could not run or finish this accepted address; no provider conclusion was established.	Resubmit the job later. If it repeats, contact support with the jobId.