> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/getting-started/errors.md).

# Errors

The API uses standard HTTP status codes and returns detailed error information in a consistent JSON format:

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}  // Optional field-specific errors
  }
}
```

#### Error Codes

| Status | Code                  | Description                                                          |
| ------ | --------------------- | -------------------------------------------------------------------- |
| 400    | `bad_request`         | The request was invalid or malformed                                 |
| 401    | `unauthorized`        | Authentication is required or has failed                             |
| 403    | `forbidden`           | You do not have permission to access this resource                   |
| 403    | `invalid_scope`       | Missing required OAuth scope                                         |
| 404    | `not_found`           | The requested resource does not exist                                |
| 409    | `conflict`            | The request conflicts with the current state (e.g., duplicate email) |
| 422    | `validation_error`    | The request data failed validation                                   |
| 429    | `rate_limit_exceeded` | Too many requests                                                    |
| 500    | `internal_error`      | An unexpected server error occurred                                  |

#### Validation Errors

Validation errors include additional details about which fields failed:

```json
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "fieldErrors": {
        "email": ["Invalid email format"],
        "name": ["String must contain at least 1 character(s)"]
      }
    }
  }
}
```
