Errors
The Invoance API uses standard HTTP status codes and a consistent JSON error structure across all endpoints. Errors are deterministic — the same invalid request always returns the same error code.
Error format
All error responses return a single JSON object with a machine-readable error code and a human-readable message. Never parse the message field programmatically — use the error field only.
4xx / 5xxError response
{
"error": "invalid_event_type",
"message": "event_type is required and must be <= 128 chars."
}HTTP status codes
200OKRequest succeeded.
201CreatedResource created successfully.
400Bad RequestInvalid request body or failed validation.
401UnauthorizedMissing or invalid authentication credentials.
403ForbiddenInsufficient scope or access denied.
404Not FoundThe requested resource does not exist.
409ConflictDuplicate record or resource already exists.
429Too Many RequestsRate limit exceeded. Back off and retry.
500Internal Server ErrorUnexpected server error. Contact support if persistent.
Error codes
Use the error field to handle specific failure conditions in your integration. The status code provides the HTTP category; the error code provides the exact reason.
missing_api_key401Authorization header not provided.invalid_api_key401API key not recognized or malformed.api_key_revoked401API key is inactive or has been revoked.permission_denied403Required scope is missing from the API key.invalid_payload400Request body is malformed or fails validation.invalid_signature400Ed25519 signature or payload hash mismatch.document_not_found404Requested document event does not exist.attestation_not_found404Requested AI attestation does not exist.duplicate_event409An event with this idempotency key already exists.rate_limit_exceeded429Too many requests. Retry after the indicated delay.Retry guidance
400 errorsDo not retry. Fix the request before resending.401 / 403 errorsDo not retry. Check your API key and scopes.404 errorsDo not retry. The resource does not exist.409 errorsDo not retry writes. Use the returned existing record.429 errorsRetry after the delay indicated in the Retry-After header.500 errorsRetry with exponential backoff. Contact support if persistent.