Documentation Index
Fetch the complete documentation index at: https://developer.prove.com/llms.txt
Use this file to discover all available pages before exploring further.
Scope
This page lists HTTP status codes, code / message pairs on request errors, rate-limit response headers, and replay behavior. It complements operation-specific pages in Reference.
API conventions
JSON responses omit:
- Optional fields with no value.
- Empty JSON objects.
- Empty JSON arrays.
HTTP status codes
| Code | Definition | Description |
|---|
| 200 | OK | The request completed successfully. |
| 400 | Bad Request | There was a problem with the submitted request. |
| 401 | Unauthorized | The request lacks valid authentication credentials for the target resource. Check for missing characters or whitespace. Confirm region (US or EU) and tier (Production or Sandbox) match the endpoint. |
| 403 | Forbidden | The client doesn’t have permission to access the target resource. |
| 404 | Not Found | The server didn’t find anything matching the Request-URI. |
| 429 | Too Many Requests | The rate limit of 25 requests per second has been exceeded. Wait for the time specified in the Retry-After header before making more requests. |
| 500 | Internal Server Error | The server encountered an unexpected condition preventing it from fulfilling the request. Retry the request, and if the problem persists, contact Prove support. |
HTTP 403
A 403 Forbidden response means the client isn’t allowed to access the resource as requested.
Typical causes
- Incorrect URL: Typo in the path, wrong host or region, or invalid path segment. A common mistake is treating the token URL like a versioned API path (for example appending
/v3 to the token endpoint).
- Incorrect HTTP method: The endpoint expects a specific verb (POST, GET, and so on). The wrong method can produce 403 Forbidden.
Resolution
- URL: Match the domain, full path, and any version prefix to the reference for the operation.
- Method: Use the HTTP verb documented for that endpoint.
- Request shape: Align headers, body, and
Content-Type with that operation’s reference.
API error codes
On request errors, the JSON body includes a code field and a message field.
| Error code | Description | Resolution path |
|---|
| 8000 | Internal Error | The server encountered an unexpected condition preventing it from fulfilling the request. Retry the request, and if the problem persists, contact Prove support. |
| 8001 | Malformed Request | Request must be valid JSON, at most 4 KB, with valid parameters. Invalid parameters and reasons appear in message. |
| 8002 | Unauthorized Request | The request lacks valid authentication credentials for the target resource. Use the correct credentials. |
| 8003 | Step Called Out of Order | The request called an endpoint out of order. Use the next field for the correct endpoint. |
| 8007 | Sandbox User Not Found | Use test user inputs only unless the test case specifies otherwise. |
| 8008 | Invalid Correlation ID | Correlation ID must be valid and unique per session. |
| 8009 | Sandbox Test User Access Denied | Product credentials must match the test user’s Prove solution. |
| 8010 | Unauthorized for Country | (1) Tenant not authorized to verify numbers for that country — contact your Prove representative. (2) Region mismatch — EU number sent to the US endpoint or the reverse; use the endpoint that matches the phone number. |
| 8011 | Identity Not Found | No identity exists for the provided Identity ID. |
| 8019 | Device has been revoked | Returned when the customer tries to authenticate with a phone number tied to a revoked Prove Key. Resolution: Confirm with the customer, then start a new POST /v3/unify session and complete possession. |
Rate limiting
Prove APIs enforce 25 requests per second. Above that limit, responses use HTTP 429 and include:
| Header | Description |
|---|
X-RateLimit-Limit | Maximum requests allowed per second |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix epoch seconds when the limit resets |
Retry-After | Seconds to wait before another request |
Example rate limit response
{
"code": 8018,
"message": "Rate limit exceeded. Please wait before making more requests."
}
X-RateLimit-Remaining reflects remaining quota in the window.- After 429, wait at least
Retry-After seconds before retrying; exponential backoff is appropriate for repeated throttling.
- Spread traffic over time instead of bursts.
Replay after errors
After a non-200 response, a corrected request may be retried. After a 200 response for a step, repeating the same request returns HTTP 403 with a message such as step called out of order or correlation ID is expired or invalid, limiting replay and replay-style abuse.
