Escopos e erros
Os escopos que uma chave pode ter, os erros que qualquer endpoint pode responder e o limite de requisições.
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. |
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. |
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).