# Errors (/docs/errors)



The API uses conventional HTTP status codes. Error bodies follow a consistent shape.

## Error shape [#error-shape]

```json
{
  "statusCode": 400,
  "message": "quantityTarget must be a positive integer",
  "error": "Bad Request"
}
```

Validation errors (from class-validator) return an array of messages:

```json
{
  "statusCode": 400,
  "message": [
    "productId should not be empty",
    "quantityTarget must be >= 1"
  ],
  "error": "Bad Request"
}
```

## Status codes [#status-codes]

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `200` | Success                                            |
| `201` | Created                                            |
| `204` | No content (success, empty body)                   |
| `400` | Validation error or malformed request              |
| `401` | Missing or invalid bearer token                    |
| `403` | Authenticated but not authorized for this resource |
| `404` | Resource not found or not visible to your org      |
| `409` | Conflict (e.g., duplicate slug)                    |
| `429` | Rate limit exceeded — see `Retry-After`            |
| `500` | Unexpected server error (tracked, retry later)     |

## Idempotency [#idempotency]

Mutation endpoints are not yet idempotent. If a `POST` fails with a 5xx or network error, inspect the resource before retrying to avoid duplicates.

Idempotency key support is on the roadmap.