# Ámbitos y errores

> Los ámbitos que puede tener una clave, los errores que puede responder cualquier endpoint y el límite de solicitudes.

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

<a id="scopes"></a>

## Ámbitos

Cada clave tiene sus propios ámbitos, que se eligen al crearla.

| Ámbito | Qué permite |
| --- | --- |
| `members:read` | Consultar tus artistas y sellos. |
| `members:write` | Invitar a nuevos artistas y sellos a tu cuenta. |
| `catalog:read` | Lanzamientos, pistas y su entrega a las plataformas. |
| `earnings:read` | Ingresos por mes, lanzamiento o plataforma. |
| `payouts:read` | Tu saldo y tus solicitudes de retiro. |
| `links:read` | Smart links y pre-saves con sus estadísticas. |
| `ddex:write` | Entregar lotes DDEX ERN (zip; se recomienda 4.3 y se aceptan 4.2/4.1/3.8.x/3.7) que se convierten en borradores de lanzamiento, y consultar su estado. |
| `ddex:validate` | Probar mensajes y lotes ERN (en cualquier versión aceptada) con todas las comprobaciones de una entrega; no se crea nada. |
| `webhooks:read` | Consultar tus endpoints de webhook y lo que se les ha enviado. |
| `webhooks:write` | Crear, modificar y eliminar endpoints de webhook, renovar sus secretos, enviar eventos de prueba y reintentar entregas. |

<a id="errors"></a>

## Errores

Los errores responden `{ "error": "…", "code": "…" }` (más `field` si un dato no es válido y `scope` si falta un ámbito).

| Estado | Código | Significado |
| --- | --- | --- |
| 400 | `invalid` | Un parámetro es incorrecto; field indica cuál. |
| 401 | `unauthenticated` | Falta la cabecera Authorization: Bearer. |
| 401 | `invalid_key` | La clave no existe. |
| 401 | `key_revoked / key_expired` | La clave se revocó o ha caducado. Crea una nueva. |
| 401 | `test_keys_retired` | Una clave de prueba (hm_test_…), retirada el 12 de octubre de 2026. Usa una clave de producción (hm_live_…) y haz las pruebas con POST /ddex/validate. |
| 403 | `insufficient_scope` | A la clave le falta el ámbito que necesita este endpoint; scope indica cuál. |
| 403 | `account_inactive` | Tu cuenta no está activa. |
| 403 | `api_not_in_plan` | Tu plan no incluye la API. Se incluye en los planes Enterprise y Custom. |
| 404 | `not_found` | El endpoint no existe, o el recurso no es tuyo. |
| 429 | `rate_limited` | Más solicitudes por minuto con esta clave de las que permite tu plan (X-RateLimit-Limit). Espera los segundos que indique Retry-After. |

<a id="rate-limits"></a>

## Límites de solicitudes

Las solicitudes por minuto y clave dependen de tu plan (120 en Enterprise; en Custom, según tu volumen). `X-RateLimit-Limit` indica el tuyo, cada respuesta lleva `X-RateLimit-Remaining` y un 429 lleva `Retry-After` (en segundos).

Fuente: https://developer.hillsmusic.com/es/reference/scopes-and-errors/