Error codes

When integrating Payrails API, you can sometimes receive an error response. We make it easy to understand and fix those errors so that our systems can integrate smoothly.

HTTP status codes

Our API replies with different HTTP status codes as the first layer of information on the results of your requests. However, always remember that it is important to dig deeper into the response body to understand the reason for the status code.

HTTP status code 200 can still mean a declined paymentWhen requesting a payment authorization, an HTTP status code 200 doesn’t mean that the payment was successful, but just that the communication with the Payment Provider was done successfully. However, their response could’ve been that the payment was declined, so analyze the response body to find the result.

The following is the list of HTTP status codes that our API can return.

Status	Summary	Description
200	OK	Everything worked as expected.
201	Created	Your request was successful, and a new resource has been created.
202	Accepted	Your request was accepted for processing, but the processing has not been completed. Check our notifications documentation for how to handle these.
400	Bad Request	The server cannot process your request due to a client error (e.g., malformed syntax).
401	Unauthorized	Authentication is required, and your request lacks valid authentication credentials.
403	Forbidden	We understood your request but refused to authorize it with your current authentication.
404	Not Found	We cannot find the requested resource.
405	Method Not Allowed	The method specified in your request is not allowed for the resource.
408	Request Timeout	The request timed out.
409	Conflict	Your request conflicts with the current state of the resource.
413	Request Entity Too Large	Your request size exceeds the max limit allowed for the resource.
422	Unprocessable Entity	We are unable to process your request with the provider parameters or body. Check the response body for more details.
429	Too Many Requests	You’ve sent too many requests in a given amount of time.
499	Request Canceled	The request was canceled by the client before the server could process it.
500	Internal Error	You should never get this error, but in case you do, please contact our Support Team.
503	Service Unavailable	The request cannot be processed due to unavailability of service (e.g provider connection error).
504	Gateway Timeout	A downstream service did not respond in time.

Error structure

All the 4xx errors will specify details about the problem inside the response body. Those errors will have the structure explained in the following table.

Field	Type	Description
`id`	UUID	Identifier of the error request in Payrails system. Please share this value when working with our team to debug the error.
`code`	String	Machine-friendly code for the error. The next section contains a list of all possible values, meanings, and resolutions.
`detail`	String	Text explaining the error in Human readable format.
`docUrl`	URL	Direct link to the documentation of the error.
`reason`	Object	Optional. Additional information about the context of this error.

When returned by our API, these errors look like this:

json

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "workflow.action.failed",
      "detail": "The execution of the requested workflow action failed",
      "docUrl": "https://docs.payrails.com/docs/error-codes#workflowactionfailed",
      "reason": { /*This includes more details about the reason of the error and includes some optional values.*/ }
    }
  ]
}

The optional reason section can look like this, for the case of a rejected payment attempt:

"reason": {
  "category": "Instrument",
  "result": "BlockedInstrument",
  "source": "Customer",
  "detail": "LostInstrument"
}

List of error codes

The following is a list of the possible values for the code field in Payrails errors, and some advice on how to fix them.

`request.malformed`

Description	The format or structure of your request does not adhere to the required specifications. It could be due to missing or incorrectly formatted parameters, invalid JSON, or other syntactical errors within the request payload.
Resolution	Double-check your request payload, parameters, and structure against our API documentation.

`request.blocked`

Description	Your request content was blocked by our content safety policy.
Resolution	Review and revise your request content, then retry.

`request.unauthorized`

Description	Your request lacks the necessary credentials to access the requested resource or perform the specified action.
Resolution	Check if your headers contain the necessary and valid access token. You can obtain a new one by calling the Access Token API.

`request.forbidden`

Description	Your request is properly authenticated, but your credentials lack the required permissions to perform the requested operation.
Resolution	Check the roles and permissions of your current credentials.

`request.not-found`

Description	The requested resource was not found in our system.
Resolution	Double-check the URL or the resource identifier to ensure its correctness.

`request.timeout`

Description	The request timed out.
Resolution	You can retry the request, with the same idempotency key if the endpoint requires one.

`request.conflict`

Description	Your requested operation cannot be completed due to a conflict with the current state of the resource.
Resolution	Check for specific error details or additional information provided in the error response to understand the nature of the conflict.

`request.entity-too-large`

Description	Your request size exceeds the max limit allowed for the resource.
Resolution	Reduce the size of the request you are sending.

`request.header.missing`

Description	Your request is missing a required header.
Resolution	Check the specific error in the response body to know which parameter is missing.

`request.header.invalid`

Description	Your request contains a header that is not in the required format or its value is not the expected one.
Resolution	Check the specific error in the response body to know which header is invalid.

`request.param.missing`

Description	Your request is missing a required parameter.
Resolution	Check the specific error in the response body to know which parameter is missing.

`request.param.invalid`

Description	Your request contains a header that is not in the required format or its value is not the expected one.
Resolution	Check the specific error in the response body to know which parameter is invalid.

`request.method-not-allowed`

Description	Your request method is not in the required format or its value is not the expected one.
Resolution	Retry the request using the standard method for the operation.

`request.canceled`

Description	The request was canceled by the client before the server could process it.
Resolution	Retry sending the request in case you want to complete it.

`request.rate-limit`

Description	You have sent too many requests in a short duration.
Resolution	Retry sending the request after some time.

`workflow.action.not-allowed`

Description	The action you’re requesting is not allowed for this workflow or for its current state. For example, you cannot execute a Capture action without a successful Authorize action before.
Resolution	Check your workflow configuration with the Payrails team.

`workflow.action.failed`

Description	There was a problem during the execution of a Workflow Action.
Resolution	Check the response body for more specific information about the problem under the reason field. There you will find result from Result Codes, category, source and detail.

`workflow.rule.failed`

Description	There was a problem during the resolution of a Rule in your Workflow.
Resolution	Check the response body for more specific information about the problem.

`internal`

Description	Something wrong happened inside Payrails system.
Resolution	Contact Payrails Support Team.

`service.unavailable`

Description	The request cannot be processed due to unavailability of service, connection outage or timeout.
Resolution	Retry sending the request or contact Payrails Support Team.

`service.timeout`

Description	A downstream service did not respond in time, so Payrails stopped waiting and returned this error.
Resolution	Retry the request, with the same idempotency key if the endpoint requires one. If the error persists, contact Payrails Support Team.

Getting Started

Payment Orchestration

Merchant of Record

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

HTTP status codes

Error structure

List of error codes

`request.malformed`

`request.blocked`

`request.unauthorized`

`request.forbidden`

`request.not-found`

`request.timeout`

`request.conflict`

`request.entity-too-large`

`request.header.missing`

`request.header.invalid`

`request.param.missing`

`request.param.invalid`

`request.method-not-allowed`

`request.canceled`

`request.rate-limit`

`workflow.action.not-allowed`

`workflow.action.failed`

`workflow.rule.failed`

`internal`

`service.unavailable`

`service.timeout`

​HTTP status codes

​Error structure

​List of error codes

​request.malformed

​request.blocked

​request.unauthorized

​request.forbidden

​request.not-found

​request.timeout

​request.conflict

​request.entity-too-large

​request.header.missing

​request.header.invalid

​request.param.missing

​request.param.invalid

​request.method-not-allowed

​request.canceled

​request.rate-limit

​workflow.action.not-allowed

​workflow.action.failed

​workflow.rule.failed

​internal

​service.unavailable

​service.timeout

HTTP status codes

Error structure

List of error codes

`request.malformed`

`request.blocked`

`request.unauthorized`

`request.forbidden`

`request.not-found`

`request.timeout`

`request.conflict`

`request.entity-too-large`

`request.header.missing`

`request.header.invalid`

`request.param.missing`

`request.param.invalid`

`request.method-not-allowed`

`request.canceled`

`request.rate-limit`

`workflow.action.not-allowed`

`workflow.action.failed`

`workflow.rule.failed`

`internal`

`service.unavailable`

`service.timeout`