# Escopos e erros

> Os escopos que uma chave pode ter, os erros que qualquer endpoint pode responder e o limite de requisições.

<!-- 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>

## Escopos

Cada chave tem seus próprios escopos, escolhidos quando ela é criada.

| Escopo | O que permite |
| --- | --- |
| `members:read` | Listar seus artistas e gravadoras. |
| `members:write` | Convidar novos artistas e gravadoras para a sua conta. |
| `catalog:read` | Lançamentos, faixas e a entrega deles às plataformas. |
| `earnings:read` | Receita por mês, lançamento ou plataforma. |
| `payouts:read` | Seu saldo e suas solicitações de saque. |
| `links:read` | Smartlinks e pré-saves com as estatísticas. |
| `ddex:write` | Entregar lotes DDEX ERN (zip; 4.3 recomendado, 4.2/4.1/3.8.x/3.7 aceitos) que viram lançamentos em rascunho, e ler o status deles. |
| `ddex:validate` | Testar mensagens e lotes ERN (qualquer versão aceita) com todas as verificações de uma entrega; nada é criado. |
| `webhooks:read` | Listar seus endpoints de webhook e o que foi enviado a eles. |
| `webhooks:write` | Criar, alterar e excluir endpoints de webhook, renovar seus segredos, enviar eventos de teste e reenviar entregas. |

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

## Erros

Os erros respondem `{ "error": "…", "code": "…" }` (mais `field` para entrada inválida e `scope` para escopo ausente).

| Status | Código | Significado |
| --- | --- | --- |
| 400 | `invalid` | Um parâmetro está errado; field indica qual. |
| 401 | `unauthenticated` | Sem o header Authorization: Bearer. |
| 401 | `invalid_key` | A chave não existe. |
| 401 | `key_revoked / key_expired` | A chave foi revogada ou expirou. Crie uma nova. |
| 401 | `test_keys_retired` | Uma chave de teste (hm_test_…): desativada em 12 de outubro de 2026. Use uma chave de produção (hm_live_…) e teste com POST /ddex/validate. |
| 403 | `insufficient_scope` | Falta à chave o escopo exigido por este endpoint; scope indica qual. |
| 403 | `account_inactive` | Sua conta não está ativa. |
| 403 | `api_not_in_plan` | Seu plano não inclui a API. Ela vem com os planos Enterprise e Custom. |
| 404 | `not_found` | Esse endpoint não existe, ou o recurso não é seu. |
| 429 | `rate_limited` | Mais requisições em um minuto com esta chave do que o seu plano permite (X-RateLimit-Limit). Aguarde Retry-After segundos. |

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

## Limites de requisições

As requisições por minuto de cada chave seguem o seu plano (120 no Enterprise, definidas conforme o seu volume no Custom); `X-RateLimit-Limit` informa o seu limite, toda resposta traz `X-RateLimit-Remaining` e um 429 traz `Retry-After` (em segundos).

Fonte: https://developer.hillsmusic.com/pt/reference/scopes-and-errors/