Ámbitos y errores
Los ámbitos que puede tener una clave, los errores que puede responder cualquier endpoint y el límite de solicitudes.
Á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. |
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. |
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).