> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spacemedia.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors and status codes

> Reference for SpaceMedia API error envelopes, HTTP status codes, validation behavior, pagination metadata, and common failure patterns.

# Errors

Errors come from Laravel validation, authorization, model lookup, gateway checks, and controller-specific business rules.

## Standard error envelope

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}
```

## Common status codes

| Status | Meaning                                                                                                                      |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Bad request, invalid token state, malformed date range, or business rule failure.                                            |
| `401`  | Missing bearer token, invalid API credentials, expired token, or admin-only dashboard action attempted without admin access. |
| `402`  | Organization or user quota, or a payment requirement, blocks the action.                                                     |
| `403`  | Laravel policy denied the action. The endpoint exists but the current user cannot perform it.                                |
| `404`  | Resource not found in the authenticated organization.                                                                        |
| `422`  | Validator failed or checkout/top-up input is incomplete.                                                                     |
| `500`  | Gateway, storage, or unexpected server error.                                                                                |

## Validation examples

Release create/update requires a square cover image between 3000x3000 and 5000x5000 pixels, at least one Primary Artist, valid title/version metadata, and a valid release format.

Track create/update normalizes ISRC and ISWC values before validation and requires at least one Primary Artist plus at least one Composer credit.

Revenue split create/update requires a beneficiary by existing user UUID, invited email, or existing beneficiary email, and must include either a date range or at least one release/track assignment.

## Pagination

Paginated `ApiResponse` responses include `meta`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": [],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 10,
    "total": 0,
    "from": null,
    "to": null
  }
}
```