Skip to main content

Errors

In the course of interacting with PaymentsAI, you may encounter various error codes that indicate issues with your requests. These errors provide specific feedback about what went wrong so you can identify and resolve them quickly.

Each error below lists the HTTP status code, the type of error, the underlying problem, and a suggested solution.

Error response format​

Every error response is a JSON object with a consistent shape:

{
  "errorCode": "string",
  "statusCode": 400,
  "message": "Bad request",
  "details": "string"
}
  • statusCode: The HTTP status code, repeated in the body.
  • message: A human-readable description of the error.
  • errorCode: An opaque identifier string. Treat it as a value to log, not to branch on. Drive programmatic decisions off statusCode and message.
  • details: Present only on some errors (400 and 422), with extra information about what specifically failed validation.

Per-endpoint error codes​

Different endpoints return different subsets of these codes. The most common:

Endpoint familyReturns
POST /transactions400, 401, 500
POST /transactions/{id}/refund400, 401, 403, 409, 422, 500
GET/POST customers, payment instruments400, 401, 403, 404, 500
Subscriptions400, 401, 403, 500
Subscription cancellations400, 401, 403, 404, 409, 500

The 409 and 422 codes apply mainly to refunds and cancellations, where the state of an existing resource matters.

400 Bad request​

  • HTTP Status Code: 400
  • Type: Bad request
  • Problem: Your payload is incorrect (wrong data)
  • Solution: In most cases, the problem is with the request itself. Please verify your payload with our OpenAPI docs.
{
  "errorCode": "string",
  "statusCode": 400,
  "message": "Bad request",
  "details": "string"
}

401 Missing auth token​

  • HTTP Status Code: 401
  • Type: Missing auth token
  • Problem: PaymentsAI can't authenticate you with the information provided
  • Solution: Use the correct API key. Make sure you aren't using a key that you revoked.
{
  "errorCode": "string",
  "statusCode": 401,
  "message": "Missing auth token"
}

403 Forbidden access​

  • HTTP Status Code: 403
  • Type: Forbidden access
  • Problem: PaymentsAI recognizes your credentials, but you don't have permission to access this resource
  • Solution: Please contact support.
{
  "errorCode": "string",
  "statusCode": 403,
  "message": "Forbidden access"
}

404 Not found​

  • HTTP Status Code: 404
  • Type: Not found
  • Problem: The resource you requested does not exist (for example, a transaction, customer, or payment instrument ID that is wrong or belongs to another organization)
  • Solution: Verify the ID in the URL path and that it belongs to your organization.
{
  "errorCode": "string",
  "statusCode": 404,
  "message": "Not found"
}

409 Conflict​

  • HTTP Status Code: 409
  • Type: Conflict
  • Problem: The request conflicts with the current state of the resource, such as refunding a transaction that is already fully refunded or canceling a subscription that is already canceled
  • Solution: Fetch the current state of the resource with a GET and reconcile before retrying. The body has no details field for this error.
{
  "errorCode": "string",
  "statusCode": 409,
  "message": "Conflict with the current state of the target resource"
}

413 Request entity too large​

  • HTTP Status Code: 413
  • Type: Request entity too large
  • Problem: The request payload is too large for the server to process
  • Solution: Reduce the size of the request payload. Ensure that files or data sent are within the allowed limits (4mb).
{
  "errorCode": "string",
  "statusCode": 413,
  "message": "Request entity too large"
}

422 Unprocessable content​

  • HTTP Status Code: 422
  • Type: Unprocessable content
  • Problem: The request is well-formed but the values cannot be processed (for example, a refund amount greater than the refundableAmount, zero or negative, or with invalid precision)
  • Solution: Read the details field, which describes what specifically failed, correct the value, and retry.
{
  "errorCode": "string",
  "statusCode": 422,
  "message": "Unprocessable content",
  "details": "string"
}

429 Too many requests​

  • HTTP Status Code: 429
  • Type: Too many requests
  • Problem: You have sent too many requests in a given amount of time, exceeding the rate limits set by PaymentsAI
  • Solution: Add a delay before retrying your requests, gradually increasing the delay with each attempt. Check and reduce the frequency of your requests.
{
  "errorCode": "string",
  "statusCode": 429,
  "message": "Too many requests"
}

500 Internal server error​

  • HTTP Status Code: 500
  • Type: Internal server error
  • Problem: An unexpected error occurred on the server
  • Solution: Try the request again later. If the issue persists, please contact support.
{
  "errorCode": "string",
  "statusCode": 500,
  "message": "Internal server error"
}

Declined transactions are not errors​

A declined payment is not an HTTP error. A POST /transactions that the gateway declines returns a successful HTTP response (201) with a transaction whose result is declined. Check the transaction result, not the HTTP status, to detect declines. The API response does not include the gateway's raw issuer decline code; the specific reason is available in the PAI panel. See Transaction statuses.