> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blinksale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understanding and handling errors in the Blinksale API

# Error Handling

The Blinksale API uses conventional HTTP response codes to indicate the success or failure of an API request. Here's a guide to understanding and handling errors in the Blinksale API.

## HTTP Status Codes

| Code                        | Description                                                                     |
| --------------------------- | ------------------------------------------------------------------------------- |
| `200 OK`                    | The request was successful                                                      |
| `201 Created`               | Resource was successfully created                                               |
| `400 Bad Request`           | The request was invalid or could not be processed                               |
| `401 Unauthorized`          | Authentication failed or token is invalid                                       |
| `403 Forbidden`             | The authenticated user doesn't have permission to access the requested resource |
| `404 Not Found`             | The requested resource does not exist                                           |
| `422 Unprocessable Entity`  | Validation errors occurred                                                      |
| `429 Too Many Requests`     | Rate limit exceeded                                                             |
| `500 Internal Server Error` | Something went wrong on the server                                              |

## Error Response Format

All error responses from the API follow a consistent structure:

```json theme={null}
{
  "success": false,
  "message": "A descriptive error message",
  "errors": {
    // Validation errors or additional details (if applicable)
  }
}
```

For validation errors (422 status code), the `errors` object will contain field-specific error messages:

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "email": [
      "The email must be a valid email address."
    ]
  }
}
```

## Common Error Types

### Authentication Errors

If your API token is invalid or expired, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "success": false,
  "message": "Unauthenticated."
}
```

### Permission Errors

If you attempt to access or modify a resource you don't have permission for, you'll receive a `403 Forbidden` response:

```json theme={null}
{
  "success": false,
  "message": "You do not have permission to access this resource."
}
```

### Resource Not Found

When requesting a resource that doesn't exist, you'll get a `404 Not Found` response:

```json theme={null}
{
  "success": false,
  "message": "Resource not found."
}
```

### Validation Errors

If your request contains invalid data, you'll receive a `422 Unprocessable Entity` response with specific validation errors:

```json theme={null}
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "client_id": [
      "The selected client id is invalid."
    ],
    "line_items": [
      "At least one line item is required."
    ]
  }
}
```

### Rate Limiting Errors

If you exceed the API rate limits, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "success": false,
  "message": "Too many requests. Please try again after {seconds} seconds."
}
```

## Best Practices for Error Handling

When working with the Blinksale API, consider these best practices for handling errors:

1. **Check the HTTP status code** first to determine the general category of the error.
2. **Parse the error message** for more specific information about what went wrong.
3. **Handle validation errors** by checking the `errors` object and addressing each field with issues.
4. **Implement exponential backoff** for rate limiting errors to automatically retry after a waiting period.
5. **Log detailed error information** in your application to help troubleshoot issues.
6. **Display user-friendly error messages** to end-users rather than raw API error responses.

## Debugging Tips

If you're encountering errors when working with the API:

1. **Double-check your request parameters** against the API documentation.
2. **Verify your authentication token** is valid and properly formatted.
3. **Check organization access** to ensure you have permission for the operation.
4. **Review your rate limit usage** in the response headers.
5. **Contact support** if you're encountering unexpected server errors.