# Error Handling

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.

## Error Response Structure

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.

### Example Error Response


```json
{
    "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"
}
```

### Field Descriptions

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.

### API Response Code Guide

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. |


### Best Practices for Handling Errors

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.