Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api.corpay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

In addition to standard HTTP error responses, Fleet API may return functional (business) errors when a request is syntactically valid but cannot be processed due to business rules or system state. These errors are returned as structured responses containing:
  • An errorCode
  • An errorDescription
  • An appropriate HTTP statusCode
This document describes the functional error codes that clients may encounter and how to interpret them.

​
Error Response Format

When a functional error occurs, the API returns a response in the following format: 
{
  "errorCode": "ER-001",
  "errorDescription": "Invalid Card Number"
}
Clients should always inspect both:
  • The HTTP status code
  • The errorCode in the response body

​
Functional Error Codes

​
ER-001 — Invalid Card Number

HTTP Status: 400 Bad Request Description
The supplied card number is not valid or does not exist in the Corpay system. Common causes:
  • Incorrect card number format
  • Card number does not belong to the authenticated customer
  • Card has been decommissioned

​
ER-002 — Card Already Lodged

HTTP Status: 422 Unprocessable Entity Description
The card has already been lodged and cannot be lodged again. Common causes:
  • Repeated lodging request for the same card
  • Duplicate processing after a successful lodge operation

​
ER-003 — Customer Associated With Card Is Not Active

HTTP Status: 400 Bad Request Description
The customer account linked to the card is not in an active state. Common causes:
  • Customer is blocked or closed
  • Card action attempted on an inactive account

​
ER-004 — Card Is Not Active

HTTP Status: 400 Bad Request Description
The requested operation cannot be performed because the card is not active. Common causes:
  • Card is blocked or cancelled
  • Operation requires an active card state

​
ER-005 — Invalid Request Parameters

HTTP Status: 400 Bad Request Description
One or more request parameters failed validation. Notes:
The error message may include the invalid property name. Example: 
Invalid request parameters: vehicleRegNumber

​
ER-006 — Invalid Request Parameter: customerAccountNumber

HTTP Status: 400 Bad Request Description
The provided customerAccountNumber is invalid. Common causes:
  • Missing customer account number
  • Invalid or unknown account number format

​
ER-007 — Error Returned From Downstream Service

HTTP Status: 400 Bad Request Description
A validation or processing error was returned by an internal or downstream service. Notes:
The returned errorDescription may vary depending on the underlying service failure.

​
ER-009 — Invalid Hierarchy Level

HTTP Status: 400 Bad Request Description
The requested operation violates the allowed customer hierarchy rules. Common causes:
  • Sub-customer creation beyond supported hierarchy depth
  • Invalid parent - child relationship

​
ER-010 — Invalid cardIdentifier

HTTP Status: 400 Bad Request Description
The supplied cardIdentifier is invalid or does not exist. Common causes:
  • Incorrect identifier value
  • Card does not belong to the authenticated customer
  • Card has been removed from the system

​
ER-011 — Card Not Replaced Successfully

HTTP Status: 400 Bad Request Description
The card replacement process failed. Action required:
Please contact Corpay support or an administrator for further investigation.

​
ER-012 — The server encountered an unexpected condition and could not complete the request. Please contact Corpay Support.

HTTP Status: 500 Internal Server Error Description
The server encountered an unexpected condition and could not complete the request due to Technical error. Action required:
Please contact Corpay support or an administrator for further investigation.

​
Handling Recommendations

When handling functional errors, clients should:
  • Avoid retrying 400 and 422 responses automatically
  • Display user-friendly error messages based on errorCode
  • Correct input data before resubmitting requests
  • Use query APIs as a fallback when webhook-driven flows fail
  • Log errorCode and errorDescription for support diagnostics

​
Summary

Functional error codes provide clear guidance when:
  • Business rules are violated
  • Resources are in an invalid state
  • Operations cannot be completed safely
Always rely on the errorCode rather than just the HTTP status to determine next actions.