Response Codes - Verilock

The Verilock API uses standard HTTP status codes. 2xx = success, 4xx = client error, 5xx = server error.

Success Codes

Code	Name	Description
`200`	OK	Request succeeded. Response body contains the requested data.
`201`	Created	Resource successfully created (sessions, API keys, webhooks).
`204`	No Content	Request succeeded with no response body (DELETE operations).

Client Error Codes

Code	Name	Description
`400`	Bad Request	Malformed request body, missing fields, or invalid JSON.
`401`	Unauthorized	API key is missing, invalid, or revoked.
`403`	Forbidden	Valid key but insufficient permissions. Check your plan or key scopes.
`404`	Not Found	Resource does not exist. Verify endpoint URL and resource ID.
`409`	Conflict	State conflict (e.g., approving an already-declined session).
`422`	Unprocessable Entity	Well-formed request with semantic errors. See `details` for field-level messages.
`429`	Too Many Requests	Rate limit exceeded. Respect the `Retry-After` header.

Server Error Codes

Code	Name	Description
`500`	Internal Server Error	Unexpected error on our end. Include `X-Request-Id` when contacting support.
`503`	Service Unavailable	Temporary unavailability. Retry with exponential backoff.

Error Response Format

All errors return a consistent JSON structure:

422 Unprocessable Entity

{
  "error": "validation_error",
  "message": "The given data was invalid.",
  "details": {
    "redirect_url": ["The redirect url must be a valid URL."],
    "document_type": ["The selected document type is invalid."]
  }
}

429 Too Many Requests

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 30 seconds.",
  "details": {
    "retry_after": 30
  }
}

Every response includes an X-Request-Id header. Always include this when contacting support about a specific error.