# Responses & Errors

All Portal API responses use `Content-Type: application/json`. This page describes the common response shapes, error format, and status codes.

## Success responses

| Code | HTTP Status | Description |
|------|-------------|-------------|
| 200 | OK | Resource retrieved or list returned |
| 201 | Created | Resource created; response body contains the new entity |
| 204 | No Content | Resource deleted; no response body |

Single-resource example:

```json
{
  "id": "a1b2c3d4-...",
  "name": "my-bucket",
  "createdAt": "2025-06-15T10:30:00Z"
}
```

## Error responses

All errors return a JSON object with a single `message` field:

```json
{
  "message": "Human-readable error description"
}
```

| Code | HTTP Status | Description |
|------|-------------|-------------|
| 400 | Bad Request | Malformed body, missing required field, or invalid parameter |
| 401 | Unauthorized | `X-Api-Key` header is missing, or the token is invalid or expired |
| 403 | Forbidden | Token lacks the endpoint's [required permission](https://docs.aur.lu/docs/portal-api/portal-api-overview#permissions) (`Missing permission <name>`), tenant mismatch, disabled tenant, or required component not enabled |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Duplicate name or constraint violation (e.g. bucket not empty on delete) |
| 500 | Internal Server Error | Unexpected server failure — retry after a short delay |

## Pagination

List endpoints accept `page` and `pageSize` query parameters:

- `page` — page number, starting at 1 (default: `1`)
- `pageSize` — items per page, max 100 (default: `20`)

```bash
curl -s -H "X-Api-Key: atp_YOUR_TOKEN_HERE" \
  "https://api-portal.aur.lu/api/v1/tenants/YOUR_TENANT_ID/buckets?page=2&pageSize=10"
```

Paginated responses wrap items with metadata:

```json
{
  "items": [
    { "name": "bucket-a", "..." : "..." },
    { "name": "bucket-b", "..." : "..." }
  ],
  "totalCount": 42,
  "page": 2,
  "pageSize": 10
}
```