Error Handling

The API uses standard HTTP status codes to indicate the result of each request. Always check the HTTP status code first to determine the general category of the error before inspecting the error response body.

HTTP Status Codes

• 400 Bad Request: The request was invalid or cannot be otherwise served.
• 401 Unauthorized: Authentication is required or has failed.
• 402 Payment Required: Payment is required to access the resource. This is typically returned when a service is closed in Finqu but the resource requires it. The merchant should reorder or reactivate the service to regain access.
• 403 Forbidden: You do not have permission to access the resource.
• 404 Not Found: The requested resource could not be found.
• 422 Unprocessable Entity: The request was well-formed but contains semantic errors (see Validation Errors below).
• 429 Too Many Requests: You have exceeded the rate limit.
• 500 Internal Server Error: An unexpected error occurred on the server.

Error Response Format

All error responses follow this structure:

{
  "error": {
    "message": "Description of the error.",
    "code": 1100,
    "details": [
      "Optional details about the error."
    ]
  }
}

• message: A human-readable description of the error.
• code: A numeric error code that specifies the error type (see below).
• details: (Optional) An array of additional details, such as which fields were invalid. For validation errors (HTTP 422 Unprocessable Entity), this will indicate which fields were erroneous.

Common Error Codes

Validation Errors

If your request contains invalid data, the API will return a 422 Unprocessable Entity status code. The details field will specify which fields were invalid.

Example:

{
  "error": {
    "message": "Validation failed.",
    "code": 1000,
    "details": [
      "email is required",
      "password must be at least 8 characters"
    ]
  }
}

Best Practices

• Always check the HTTP status code first to determine the general category of the error (e.g., 400 for bad request, 401 for unauthorized, 403 for forbidden, 404 for not found, 402 for payment required, 422 for validation errors, 429 for rate limits, 500 for server errors).
• Use the code and message fields in the error response to identify the specific error and provide user-friendly feedback or handle errors programmatically.
• Use the details array to provide feedback to users or to debug issues, especially for validation errors (422).
• Handle specific error codes in your application logic for better user experience.

Debugging Strategies

• Log the full error response for failed requests.
• Use the error code to identify and handle known error scenarios.
• For repeated or unexpected errors, contact support with the error response details.