The VyaFac API adheres to standard HTTP status codes to indicate the success or failure of requests. This document provides a detailed guide to common error responses and best practices for handling them effectively.
When an error occurs, the API returns a structured JSON response. This format ensures consistency across all endpoints, making it easier for clients to parse and handle errors efficiently.
{
"status": "error",
"message": "Subscription could not be found",
"meta": null,
"data": null,
"errors": [],
"code": 404,
"timestamp": "2025-02-26T10:38:19+00:00",
"version": "1.0.0"
}status (string): Indicates the response type (success or error). message (string): A human-readable description of the error. meta (object|null): Additional metadata related to the response, if applicable. data (object|null): Contains relevant data if available; null for errors. errors (array): A list of specific validation or processing errors (if applicable). code (integer): The HTTP status code for the error. timestamp (string): The server timestamp when the request occurred. version (string): API version at the time of the response.
The VyaFac system always returns a 200 OK response for successful requests. However, if an issue arises, one of the following error codes is returned. Understanding these errors helps clients respond appropriately.
| HTTP Code | Error Type | Description |
|---|---|---|
| 400 | Bad Request | The request contains invalid syntax or missing parameters. Check the response message for details. |
| 401 | Unauthorized | Authentication credentials are missing or invalid. The client must provide valid credentials. |
| 404 | Not Found | The requested resource does not exist on the server. Ensure the URL is correct. |
| 403 | Forbidden | The request is understood but denied due to insufficient permissions. |
| 405 | Method Not Allowed | The HTTP method used is not supported for the requested resource. |
| 422 | Unprocessable Entity | The request is syntactically correct but contains invalid data that cannot be processed. |
| 429 | Too Many Requests | The client has exceeded the allowed request limit (rate limiting applied). |
| 500 | Internal Server Error | An unexpected error occurred on the server. This should not happen under normal conditions. |
To ensure robust API integration, follow these best practices when handling errors:
- Log and Monitor Errors: Keep track of API responses to identify recurring issues.
- Retry Mechanisms: For transient errors like 429 Too Many Requests or 500 Internal Server Error, implement retry logic with exponential backoff.
- Validate Requests: Before making an API request, ensure that all required parameters and valid data formats are provided to avoid 400 Bad Request errors.
- Handle Authentication Issues: Implement token refresh mechanisms to prevent 401 Unauthorized errors due to expired tokens.
- Graceful User Messaging: Provide clear error messages to users instead of exposing raw API responses.
By following these guidelines, you can build more reliable and fault-tolerant API integrations with VyaFac.