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
Status Code | Meaning |
---|---|
400 | Bad Request |
401 | Unauthorized |
402 | Payment Required |
403 | Forbidden |
404 | Not Found |
422 | Unprocessable Entity |
429 | Too Many Requests |
500 | Internal Server Error |
- 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
Code | Meaning |
---|---|
1000 | Not specified |
1100 | Client not authorized |
1101 | Client not found |
1200 | POS authorization failed |
1201 | Device access denied |
1300 | Feature not in plan |
1301 | Account service closed |
1302 | Account closed |
1400 | Dependency error |
1401 | Inventory exists |
1500 | File upload failed |
1501 | File not found |
1502 | File not allowed |
1503 | File too large |
1900 | Rate limit exceeded |
1901 | Service unavailable |
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
andmessage
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.
Last updated on