Error Handling

Error Response Format
The error response follows the standard HTTP response format and includes the following properties:

'status': The HTTP status code indicating the type of error that occurred.
'title': A brief description of the error.
'errors': An object containing detailed error information. This object follows the JSON format and consists of properties representing the field names and their corresponding error messages.

Example Error Response:

{
  "status": 400,
  "title": "One or more validation errors occurred.",
  "traceId": "00-64a5cf4492a4f17b5751dce5120fe708-631875e92558b83a-01"
  "errors": {
    "username": ["The username field is required."],
    "password": [
      "The password field is required.",
      "The password must be at least 8 characters long."
    ]
  }
}

Errors Object
The modelState object provides detailed error information for each field in the request. It maps field names to an array of error messages associated with that field. If a field has multiple errors, they will be listed as separate messages in the array.

Example ModelState Object:

{
  "field1": ["error message 1", "error message 2"],
  "field2": ["error message 3"],
  "field3.subfield": ["error message 4"]
}

Common Error Codes
Here are some common HTTP status codes and their corresponding meanings:

Response Code	Description
200 OK	Your request completed successfully.
201 Created	Resource created successfully.
204 No Content	Returned on a successful DELETE.
401 Unauthorized	Enter valid credentials to continue.
403 Forbidden	Access to the requested resource is denied.
405 Method Not Allowed	The method you supplied is not allowed for that resource, for example a PUT method on a read-only resource.
500 Internal Server Error	An error occurred that could not be handled by the application.
502 Bad Gateway	An invalid response was received by the server.
503 Service Unavailable	The server is temporarily unable to handle this request.
504 Gateway Timeout	The upstream server did not respond in time.

Retry strategy

Status	Recommended behavior
`401 Unauthorized`	Refresh the access token via /oauth2/token once, then retry. Do not loop.
`500 Internal Server Error` / `502 Bad Gateway` / `504 Gateway Timeout`	Exponential backoff, up to 3 attempts.
`503 Service Unavailable`	Do not retry. Fall back to the original decline. The 503 indicates FlexFactor cannot rescue this transaction right now, and a retry will not change the outcome within the merchant decision window.

Handling Errors

To handle errors in your application, you should check the HTTP status code of the API response. If the status code indicates an error, you can parse the response body for the errors object to obtain detailed error information. You can then display the error messages to the user or take appropriate actions based on the specific error conditions.

It's important to note that the errors object may not always be present in the errors response. In such cases, you can rely on the title property to provide a general description of the error.