The Verilock API uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.
Success Codes
| Code | Name | Description |
|---|
200 | OK | The request succeeded. The response body contains the requested data. |
201 | Created | A new resource was successfully created. Returned when creating sessions, API keys, or webhook endpoints. |
204 | No Content | The request succeeded but there is no response body. Returned for DELETE operations and some updates. |
Client Error Codes
| Code | Name | Description |
|---|
400 | Bad Request | The request body is malformed, missing required fields, or contains invalid JSON. |
401 | Unauthorized | The API key is missing, invalid, or has been revoked. Check your X-API-Key header. |
403 | Forbidden | The API key is valid but does not have permission to perform this action. Check your plan or key scopes. |
404 | Not Found | The requested resource does not exist. Verify the endpoint URL and resource ID. |
409 | Conflict | The request conflicts with the current state of the resource. For example, trying to approve an already-declined session. |
422 | Unprocessable Entity | The request is well-formed but contains semantic errors. Field validation failures are returned in the details object. |
429 | Too Many Requests | You have exceeded the rate limit. Wait for the time specified in the Retry-After header before retrying. |
Server Error Codes
| Code | Name | Description |
|---|
500 | Internal Server Error | An unexpected error occurred on our end. If this persists, contact support with the request ID from the response headers. |
503 | Service Unavailable | The API is temporarily unavailable due to maintenance or high load. Retry with exponential backoff. |
error field contains a machine-readable code, message is human-readable, and details provides additional context when available.
Request ID — Every API response includes an X-Request-Id header. Include this ID when contacting support about a specific error.
Error Response -- 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."]
}
}
Error Response -- 429 Too Many Requests
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please retry after 30 seconds.",
"details": {
"retry_after": 30
}
}
