Guides

Error Handling

This section provides guidelines for handling errors in the API responses. When an error occurs during the processing of a request, the API will return an error response with a corresponding HTTP status code. The error response will also include a ModelState object in JSON format, which provides additional details about the encountered error.

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 CodeDescription
200 OKYour request completed successfully.
201 CreatedResource created successfully.
204 No ContentReturned on a successful DELETE.
401 UnauthorizedEnter valid credentials to continue.
403 ForbiddenAccess to the requested resource is denied.
409 ConflictAn idempotent request is still in progress, or an idempotency key was reused with a different payload. See Idempotency.
405 Method Not AllowedThe method you supplied is not allowed for that resource, for example a PUT method on a read-only resource.
500 Internal Server ErrorAn error occurred that could not be handled by the application.
502 Bad GatewayAn invalid response was received by the server.
503 Service UnavailableThe server is temporarily unable to handle this request.
504 Gateway TimeoutThe upstream server did not respond in time.

Retry strategy

StatusRecommended behavior
401 UnauthorizedRefresh the access token via /oauth2/token once, then retry. Do not loop.
409 Conflict (in-flight)An idempotent request is still being processed. Retry the same request and key after a short backoff. See Idempotency.
409 Conflict (reused key)The idempotency key was reused with a different payload. Do not retry — use a unique key per operation.
500 Internal Server Error / 502 Bad Gateway / 504 Gateway TimeoutExponential backoff, up to 3 attempts.
503 Service UnavailableDo 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. (Exception: a 503 from the idempotency store carries a Retry-After header and is safe to retry — see Idempotency.)

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.