Prove® Platform API Reference
Conventions, Errors, and Status Codes
Prove® Platform API Reference
Conventions, Errors, and Status Codes
Discover the conventions as well as various error and status codes generated by Prove® Platform APIs
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:
| Code | Definition | Description |
|---|---|---|
| 200 | OK | 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. |
| 403 | Forbidden | The client does not have permission to access the target resource. |
| 404 | Not Found | The server did not find anything matching the Request-URI. |
| 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. |
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.
The table has a list of the API error codes:
| 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 | Ensure the request is valid JSON, is under 4 KB in size, and correct any invalid parameters. Invalid parameters are specified with the reason in the message field. |
| 8002 | Unauthorized Request | The request lacks valid authentication credentials for the target resource - ensure the correct credentials were used. |
| 8003 | Step Called Out of Order | The request called an endpoint out of order. Check the next field for the proper endpoint to call. |
| 8007 | Sandbox User Not Found | Ensure in Sandbox environment, only test user information is used as input for requests unless otherwise specified in the test cases. |
| 8008 | Invalid Correlation ID | Ensure the correct Correlation ID is used as input for all endpoints other than Start. The Correlation ID is unique per user/session and cannot be used across transactions. |
| 8009 | Sandbox Test User Access Denied | In the sandbox environment, the test user cannot be accessed with your current product credentials. Ensure you’re using Pre-Fill test users with Pre-Fill credentials and Identity test users with Identity credentials. |
Example Success and Error Responses
| Endpoint | HTTP Code | Response Body |
|---|---|---|
| Any | 400 | {"code":8001,"message":"field 'correlationId' length cannot be greater than 36 characters"} |
| Any | 400 | {"code":8007,"message":"no test user found matching the phone number"} |
| Any | 401 | {"code":8002,"message":"not authorized"} |
| Any | 403 | {"code":8003,"message":"step not allowed"} |
| Any | 403 | {"code":8008,"message":"correlationId is expired or invalid"} |
| Any | 500 | {"code":8000,"message":"error at prove, try again later"} |
| Start | 200 | {"correlationId":"0a53cbf8-4053-4d6a-9ef4-ebebc8f26811","authToken":"eyJ...","next":\{"v3-validate":"/v3/validate"}} |
| Start | 400 | {"code":8001,"message":"field 'flowType' is missing"} |
| Start | 400 | {"code":8001,"message":"field 'flowType' must be one of these values: desktop mobile"} |
| Start | 400 | {"code":8001,"message":"field 'ssn' length cannot be greater than 9 characters"} |
| Start | 400 | {"code":8001,"message":"field 'ssn' must be numeric"} |
| Start | 400 | {"code":8001,"message":"field 'dob' must be in date format: YYYY-MM-DD, YYYY-MM, or MM-DD"} |
| Validate | 200 | {"success":true,"challengeMissing":false,"phoneNumber":"2001001686","next":\{"v3-challenge":"/v3/challenge"}} |
| Validate | 200 | {"success":true,"challengeMissing":false,"phoneNumber":"2001001686","next":\{"v3-complete":"/v3/complete"}} |
| Validate | 200 | {"success":false,"challengeMissing":false,"next":\{"done":"done"}} |
| Validate | 200 | {"success":true,"challengeMissing":true,"phoneNumber":"2001001686","next":\{"v3-challenge":"/v3/challenge"}} |
| Challenge | 200 | {"success":true,"individual":\{USER INFO...},"next":\{"v3-complete":"/v3/complete"}} |
| Challenge | 200 | {"success":false,"next":\{"v3-complete":"/v3/complete"}} |
| Challenge | 400 | {"code":8001,"message":"field 'ssn' length cannot be greater than 9 characters"} |
| Challenge | 400 | {"code":8001,"message":"field 'ssn' must be numeric"} |
| Challenge | 400 | {"code":8001,"message":"field 'dob' must be in date format: YYYY-MM-DD, YYYY-MM, or MM-DD"} |
| Complete | 200 | {"success":true,"next":\{"done":"done"}} |
| Complete | 200 | {"success":false,"next":\{"done":"done"}} |
| Complete | 400 | {"code":8001,"message":"field 'ssn' length cannot be greater than 9 characters"} |
| Complete | 400 | {"code":8001,"message":"field 'dob' must be in date format: YYYY-MM-DD, YYYY-MM, or MM-DD"} |
Retry Behavior After Errors
When a 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 ordercorrelation ID is expired or invalidProve prevents retries to ensure proper behavior and mitigate issues with replay attacks.