Understanding the errors associated with the the Orders API endpoint for evaluating risk will help you troubleshoot and handle issues when integrating with the API.
All error responses from the POST /v2/orders endpoint follow a consistent JSON structure to ensure predictable error handling. The HTTP status code in the response header indicates the general nature of the error.
The JSON body of an error response contains the following fields:
-
message (string): A human-readable description of the error. This often includes specific details about which validation rule failed.
-
errorType (string): A high-level classification of the error, such as validation, unauthorized, or internal.
-
code (number): The HTTP status code.
Example Error Response
The following is an example of a validation error for an invalid fulfillment type:
{
"message": "failed to validate input: Fulfillment type must be one of SHIPPED, DIGITAL, STORE_PICK_UP, LOCAL_DELIVERY, STORE_DRIVE_UP, IN_PERSON, ",
"errorType": "validation",
"code": 400
}
The following sections contain a detailed breakdown of possible HTTP status codes and the specific errors associated with them.
This status code indicates a problem with the client's request, usually caused by malformed syntax or invalid data.
Validation Errors (errorType: "validation")
These are the most common 400 errors and occur when the request body fails validation. Usually the base error message is "failed to validate input," followed by a more specific reason.
Other Bad Request Errors
-
"missing orderId in update order request"
-
"a problem was found with the request input"
-
"correlation id header missing"
-
"client id header missing"
-
"failure in pulling request metadata"
This indicates that the request lacks valid authentication credentials.
-
errorType: "unauthorized"
-
Message: "failed to authorize request"
-
Common Triggers:
-
The JWT provided is invalid, expired, or malformed.
-
Authentication credentials (for example, API key, token) are missing from the request.
-
This indicates that the server understands the request but refuses to authorize it because the client lacks the necessary permissions.
-
errorType: "forbidden"
-
Possible Messages:
-
"failed to show claims for access"
-
"client does not have required entitlements"
-
-
Common Triggers:
-
The authenticated client is missing the required
PAYMENTS_FRAUDorCHARGEBACK_MANAGEMENTentitlements. Speak to your account manager or customer success manager to receive clarification on the correct entitlements. -
An attempt was made to access a demo order endpoint from a non-sandbox environment.
-
This indicates that the server could not find the requested resource.
-
errorType: "client"
-
Message: "unable to retrieve requested resource. resource does not exist"
-
Common Triggers: A downstream service could not locate a resource needed to process the request.
This indicates that the request could not be completed due to a conflict with the current state of the target resource.
-
errorType: "client"
-
Message: "the resource you are attempting to create already exists."
-
Common Triggers: Attempting to create a resource (for example, an order) with an ID that already exists.
-
errorType: "internal" or "unknown_internal"
-
Possible Messages:
-
"an internal server error has occurred"
-
"an internal server error has occurred. please contact support with your correlationId"
-
-
Common Triggers: Unspecified internal processing errors
This indicates that the server is temporarily unable to handle the request, often due to being overloaded or down for maintenance.
-
errorType: "unavailable"
-
Message: "The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff"
-
Common Triggers: A critical downstream service is temporarily offline or unreachable. Equifax recommends retrying the request after a short delay (with backoff).