# Errors & responses

Response envelopes, error codes, and HTTP status mapping.

## Success responses

```json
{
  "data": { },
  "meta": { "totalCount": 42, "limit": 50, "offset": 0 }
}
```

meta is optional — list endpoints include pagination; write endpoints return 201 with the created resource in data.

## Error responses

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { }
  }
}
```

| HTTP | Code | When |
| --- | --- | --- |
| 400 | VALIDATION_ERROR | Invalid query params or request body |
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Insufficient scope (e.g. read token on write) |
| 404 | NOT_FOUND | Resource not in this organization |
| 500 | INTERNAL_ERROR | Unexpected server error |
| 503 | SERVICE_UNAVAILABLE | Database not configured |