Error Reference

This page lists the error codes you may encounter when using Emblem's hosted verification API.

Start verification errors

POST /api/v1/verify/start

Code	HTTP status	Description	What to do
`INVALID_REQUEST`	400	Malformed request body	Check that you are sending valid JSON with the expected fields.
`VALIDATION_ERROR`	400	Missing or invalid fields	Verify `integration_id`, `callback_url`, and any optional fields.
`INTEGRATION_INACTIVE`	400	Integration is disabled	Re-enable the integration in the Emblem dashboard.
`PROVIDER_INACTIVE`	400	Provider is disabled for this integration	Check your integration settings in the dashboard.
`UNAUTHORIZED`	401	Missing or invalid API key	Confirm your Bearer token is present and correct.
`ENTITLEMENT_REQUIRED`	403	Entitlement required for production verification sessions	Confirm your account is provisioned for production verification.
`PUBLISHER_SUSPENDED`	403	Tenant is suspended by Emblem	Contact Emblem support or your account owner to resolve the suspension.
`NOT_FOUND`	404	Integration ID not found	Verify that you are using the correct `integration_id` for this environment.
`RATE_LIMITED`	429	Too many requests	Respect the `Retry-After` header before retrying.
`PROVIDER_ERROR`	502	Upstream provider failed to start the session	Retry later or contact support if the problem persists.

Validate result errors

POST /api/v1/verify/validate

Code	HTTP status	Description	What to do
`VALIDATION_ERROR`	400	Missing or invalid fields	Confirm that you are sending `result_token` in the request body.
`INVALID_FORMAT`	400	Token format is wrong	Check that you are sending the exact `result_token` returned in the callback.
`INVALID_SIGNATURE`	400	Token signature does not verify	Make sure the token is unmodified and from the same Emblem environment.
`INVALID_PAYLOAD`	400	Token payload is malformed	Retry only if you suspect the token was corrupted in transit.
`EXPIRED`	400	Token TTL exceeded	Start a new verification flow and validate immediately next time.
`ALREADY_USED`	400	Token was already consumed	Use the cached validation result from your first successful validation.
`UNAUTHORIZED`	401	Missing or invalid secret bearer; public keys are not accepted	Move validation to your backend and send `Authorization: Bearer emb_sk_*`.
`FORBIDDEN`	403	Token belongs to a different integration	Validate the token using the same integration that started the session.
`NOT_FOUND`	404	No matching session found	Confirm you are validating a current token from the correct environment.

Session reconciliation errors

GET /api/v1/verify/sessions/{sessionId}

Code	HTTP status	Description	What to do
`VALIDATION_ERROR`	400	Invalid session ID	Check the `session_id` format and value.
`UNAUTHORIZED`	401	Missing or invalid API key	Confirm your secret key is present and correct.
`NOT_FOUND`	404	Session not found	Verify that the session belongs to your integration and environment.
`RATE_LIMITED`	429	Too many recovery requests	Respect the `Retry-After` header and reduce polling frequency.
`INTERNAL_ERROR`	500	Emblem-side failure	Retry later or contact support with the request ID.

Webhook failure codes

Webhook payloads use failure.code values such as PROVIDER_REJECTED, USER_CANCELLED, TIMEOUT, MAX_ATTEMPTS, and UNKNOWN for non-success verification outcomes.

See Webhooks for the full webhook failure-code reference and payload examples.

Rate limiting

Rate limits are enforced per IP address and per key:

Auth method	Limit	Scope
Public key	60 req/min	Per IP
Public key	600 req/min	Per key
Secret key	600 req/min	Per IP

When a request is rate limited, Emblem returns 429 RATE_LIMITED and includes a Retry-After header with the number of seconds to wait before retrying.