Skip to main content

​
API conventions

Prove Platform APIs follow consistent API conventions. The API responses follow these conventions:
  • Optional fields that have no values aren’t returned.
  • JSON maps that have no values aren’t returned.
  • JSON arrays that have no values aren’t returned.

​
HTTP status codes

The following table has a list of the HTTP status codes returned by the Prove services:
CodeDefinitionDescription
200OKThe request completed successfully.
400Bad RequestThere was a problem with the submitted request.
401UnauthorizedThe request lacks valid authentication credentials for the target resource. Check for no missing chars or whitespace. Validate that you are calling the correct environment such as US or EU and Production or Sandbox.
403ForbiddenThe client doesn’t have permission to access the target resource.
404Not FoundThe server didn’t find anything matching the Request-URI.
429Too Many RequestsThe rate limit of 25 requests per second has been exceeded. Wait for the time specified in the Retry-After header before making additional requests.
500Internal Server ErrorThe server encountered an unexpected condition preventing it from fulfilling the request. Retry the request, and if the problem persists, contact Prove support.

​
API error codes

When a Prove API encounters a request error, the JSON response object includes a code field and a message field to give further context. This table has a list of the API error codes:
Error CodeDescriptionResolution Path
8000Internal ErrorThe server encountered an unexpected condition preventing it from fulfilling the request. Retry the request, and if the problem persists, contact Prove support.
8001Malformed RequestEnsure the request is valid JSON, is under 4 KB in size, and correct any invalid parameters. The API specifies invalid parameters and includes the reason in the message field.
8002Unauthorized RequestThe request lacks valid authentication credentials for the target resource. Ensure you used the correct credentials.
8003Step Called Out of OrderThe request called an endpoint out of order. Check the next field for the proper endpoint to call.
8007Sandbox User Not FoundOnly use test user information as input for requests unless otherwise specified in the test cases.
8008Invalid Correlation IDCheck the Correlation ID for errors. The Correlation ID is unique per session.
8009Sandbox Test User Access DeniedYour current product credentials can’t access the test user. Ensure you’re using test users with the matching Prove solution credentials.
8010Unauthorized for CountryThis can mean one of two things:
  • The customer is not authorized to verify numbers for the requested country. Contact your Prove representative.
  • An EU number is being passed to our US endpoint, or vice versa. Use the correct endpoint for the given phone number.
8011Identity Not FoundNo identity exists for the provided Identity ID.

​
Rate limiting

Prove APIs enforce a rate limit of 25 requests per second to ensure fair resource usage and system stability. When you exceed this limit, the API returns an HTTP 429 status code with the following headers:
HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed per second
X-RateLimit-RemainingThe number of requests remaining in the current time window
X-RateLimit-ResetThe time, in Unix epoch seconds, when the rate limit resets
Retry-AfterThe number of seconds to wait before making another request

​
Example rate limit response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699632000
Retry-After: 1

{
  "code": 8012,
  "message": "Rate limit exceeded. Please wait before making more requests."
}

​
Best practices for handling rate limits

  • Check the X-RateLimit-Remaining header to track your usage.
  • Implement exponential backoff when you receive a 429 response.
  • Respect the Retry-After header value before retrying requests.
  • Distribute requests evenly over time rather than sending bursts.

​
Retry behavior after errors

When an HTTP status code other than 200 returns, you can fix and retry the request. If you retry a request that resulted in 200, you receive an HTTP 403 code with either step called out of order or correlation ID is expired or invalid. Prove prevents retries to ensure proper behavior and mitigate issues with replay attacks.