# Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

## HTTP Status Codes

| Status Code | Meaning |
|  --- | --- |
| **200** | Success |
| **201** | Resource created successfully |
| **400** | Bad request (malformed request) |
| **401** | Missing API key |
| **403** | Invalid or revoked API key |
| **404** | Resource not found |
| **422** | Validation error |
| **429** | Rate limit exceeded |
| **500** | Server error |
| **503** | Service unavailable |


## Error Response Format

All errors follow this structure:


```json
{
  "success": false,
  "errors": {
    "<field_name|__all__>": ["error message"]
  }
}
```

- `errors.__all__`: General errors not specific to a field
- `errors.<field_name>`: Errors specific to a particular field


## Common Errors

### Authentication Error (403)


```json
{
  "success": false,
  "errors": {
    "__all__": ["API key authentication failed"]
  }
}
```

### Validation Error (422)


```json
{
  "success": false,
  "errors": {
    "customer_id": ["Customer with this ID does not exist"],
    "date": ["Invalid date format. Use ISO 8601 format (YYYY-MM-DD)"],
    "lines": ["At least one line item is required"]
  }
}
```

### Not Found (404)


```json
{
  "success": false,
  "errors": {
    "__all__": ["Invoice matching query does not exist."]
  }
}
```

### Rate Limit Exceeded (429)


```json
{
  "success": false,
  "errors": {
    "__all__": ["Rate limit exceeded. Please try again later."]
  }
}
```

## Handling Errors

**Best Practices**:

- Always check HTTP status codes
- Parse the `errors` object for field-specific details
- Implement retry logic for rate limits (429) and server errors (5xx)
- Log error responses for debugging


### Example


```python
response = requests.post(url, headers=headers, json=data)

if response.status_code == 201:
    # Success
    result = response.json()
elif response.status_code == 422:
    # Validation errors
    errors = response.json()['errors']
    for field, messages in errors.items():
        print(f"{field}: {messages}")
elif response.status_code == 429:
    # Rate limited - wait and retry
    time.sleep(60)
    response = requests.post(url, headers=headers, json=data)
else:
    # Other error
    print(f"Error {response.status_code}: {response.json()}")
```

**Next:** [Explore the API Reference →](/resources)