Conventions, Errors, and Status Codes

API Conventions

The service follows consistent API conventions. A couple to note for API responses:

Optional fields that have no values are not returned - we don't use null or empty values.
JSON maps that have no values are not returned - we don't return fields with empty maps.
JSON arrays that have no values are not returned - we don't return fields with empty arrays.

HTTP Status Codes

The following table contains 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 provide further context.

The table below contains 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 4KB in size, and correct any invalid parameters. Invalid parameters will be specified with 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 previous `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 should not be used across transactions.

Example Success and Error Error Responses

This is not an exhaustive list of the response bodies, but it does show the majority of them when interacting with the API.

Endpoint	HTTP Code	Response Body
Any	400	{"code":8001,"message":"field 'correlationId' length cannot be greater than 36 characters"}
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 a 200 is returned, you can fix the request and resubmit/retry the request. The only exception is when you receive a 200, if you retry a request, you will receive a HTTP 403 with either:

Step Called Out of Order
Correlation ID is Expired or Invalid

📘
The APIs are stateful, so retries are not allowed to ensure proper behavior and to mitigate issues with replay attacks.