Errors
What PayTomorrow error responses look like and how to fix the common ones.
HTTP status codes
| Status | Meaning |
|---|---|
200 | Success. |
401 Unauthorized | The access token is missing, expired, or from the other environment. Get a new token and retry once. |
417 Expectation Failed | The request was understood but rejected. Validation errors and business-rule errors both use this status. Read errorDetails. |
5xx | Something went wrong on PayTomorrow's side. Read-only requests can be retried with backoff. For a mutation, first reconcile whether it succeeded; do not blindly repeat order creation, settlement, or refunds. Contact support with the request time and path when the outcome is unknown. |
Error body
Errors return JSON with the reason in errorDetails:
{
"timestamp": "2026-09-23T18:04:11.532Z",
"status": "EXPECTATION_FAILED",
"path": "/application/ecommerce/orders",
"error": "Expectation Failed",
"errorDetails": "Seems like the json you sent is missing info or has the wrong format: - property email must be a valid email address, you sent: 'jordan@'"
}The same message is also sent in an error response header.
Common errors
A required field is missing. For Create order, the required fields are orderId, firstName, lastName, street, city, state, zip, email, loanAmount, and at least one entry in applicationItems.
zip must be at least 5 characters. ZIP+4 is accepted and trimmed to the first 5 digits.
Send the two-letter state code, like NC, not North Carolina.
returnUrl, cancelUrl, and notifyUrl must be absolute URLs with a scheme. Use https:// in production.
Item fields are camelCase: listPrice, salePrice, extendedListPrice, extendedSalePrice. Unknown fields such as sale_price are silently ignored rather than rejected, so double-check spelling.
The application couldn't be created. Usually the cart total is outside your approval range, or the shipping address is a PO box. The url shows the customer the reason and links back to your cancelUrl.
Check that the token and the API URL are from the same environment. Staging tokens don't work on api.paytomorrow.com.
Getting help
When you contact support, include:
- the environment (staging or production)
- the application
tokenorpt_id - the request
pathand the time it failed - the full
errorDetails
Never include your API password or API Signature.