# Error Reference

The Apiera API uses [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) for error responses.

## Error Response Format

All errors return a Problem Details JSON object:


```json
{
  "type": "https://docs.apiera.io/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "instance": "/v1/products/abc123",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Field | Description |
|  --- | --- |
| `type` | URI reference identifying the problem type |
| `title` | Short, human-readable summary |
| `status` | HTTP status code |
| `detail` | Human-readable explanation |
| `instance` | URI reference to the specific occurrence |
| `correlationId` | Unique identifier for tracking and support |


## Common Errors

### Client Errors (4xx)

400 Bad Request
Malformed request syntax or invalid parameters

401 Unauthorized
Missing or invalid authentication credentials

403 Forbidden
Authenticated but lacking required permissions

404 Not Found
Requested resource does not exist

409 Conflict
Request conflicts with the current resource state

422 Unprocessable Entity
Request contains validation errors

429 Too Many Requests
Rate limit exceeded

### Server Errors (5xx)

500 Internal Server Error
Unexpected server error occurred

503 Service Unavailable
Downstream service temporarily unavailable

504 Gateway Timeout
Downstream service timed out

## Validation Errors

Validation errors (422) include an `errors` array:


```json
{
  "type": "https://docs.apiera.io/problems/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The request was well-formed but contains semantic errors.",
  "instance": "/v1/products",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "code": "INVALID_SKU",
      "message": "SKU must be unique within the product family"
    },
    {
      "code": "REQUIRED_FIELD",
      "message": "Field 'name' is required"
    }
  ]
}
```

## Using Correlation IDs

Include the `correlationId` when contacting support to help diagnose issues quickly.