Erros e limites

Formato dos erros#

Todo erro da /api/v1 vem em application/problem+json (RFC 9457):

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "A chave não tem a permissão necessária: account:read.",
  "code": "insufficient_scope",
  "scopes": ["account:read"]
}

• code não muda entre versões: é nele que o seu aplicativo deve decidir o que fazer.
• detail é para gente ler, no idioma pedido (locale ou Accept-Language). Pode mudar de texto a qualquer momento.
• Alguns erros trazem campos a mais: errors (por campo, em validation_failed) e scopes (em insufficient_scope).

Os endereços do OAuth (/oauth/token) seguem o padrão do OAuth: { "error": "invalid_grant", "error_description": "…" }.

Códigos#

Status	code	O que fazer
400	invalid_cursor	Recomece a lista sem cursor.
400	idempotency_key_required / idempotency_key_invalid	Mande um Idempotency-Key válido (veja abaixo).
401	unauthenticated	Chave ausente, inválida ou vencida: renove uma vez com a chave de renovação e tente de novo. Se continuar, peça para autorizar de novo.
401	connection_revoked	A conexão foi desfeita (o dono desconectou em Integrações ou uma chave de renovação antiga foi usada de novo). Não renove (a renovação responde invalid_grant): peça para o dono conectar de novo.
402	insufficient_credits	Créditos insuficientes; required e available dizem quanto falta. A conta precisa de mais créditos.
403	not_acquired	A conta ainda não adquiriu o produto; adquira antes de ler os materiais.
403	subscription_inactive	A assinatura da conta não está ativa (nem em teste).
403	insufficient_scope	A chave não tem o escopo da rota. Peça a autorização de novo, com o escopo. Também aparece quando a chave da vitrine (sem conta) chama uma rota que precisa de conta.
403	personal_key_owner_only	A chave pessoal foi criada por quem não é mais o dono da conta. Peça uma chave nova ao dono atual.
403	account_inactive	A conta do HotLearn está inativa.
403	account_missing	A chave não pertence a uma conta de assinante.
404	not_found	Não existe, ou é de outra conta (o HotLearn não confirma o que é de outra conta).
404	no_connection	Chave pessoal num endereço que precisa de conexão.
405	method_not_allowed	Método errado para o endereço.
409	connection_owner_missing	Quem autorizou saiu da conta e ela está sem dono. Peça para o dono atual autorizar de novo.
409	idempotency_in_progress	Uma chamada com a mesma chave ainda está rodando. Espere Retry-After.
409	trial_limit_reached	O período de teste já usou o limite de produtos.
409	license_outdated	A licença mudou; mostre a nova e envie a versão de license.version.
409	export_not_ready	O arquivo ainda não está pronto; consulte o pedido.
410	export_expired	O arquivo venceu (24 horas); peça de novo.
422	scorm_invalid	O curso SCORM tem erros (veja errors); corrija no editor SCORM do HotLearn.
422	format_unavailable	Formato não disponível para o material; veja formats.
422	validation_failed	Dados inválidos; veja errors. Vale também para filtros das listas com valor fora do esperado (ex.: level=xyz).
422	idempotency_key_reused	A mesma chave foi usada com outros dados. Gere outra.
429	rate_limited	Limite estourado. Espere o tempo de Retry-After. Também aparece quando o mesmo endereço de rede recebe mais de 300 respostas 401 por minuto: não repita chamadas com chave inválida.
429	daily_limit_reached	A conta chegou ao limite de hoje para essa operação; veja resets_at e Retry-After (Créditos e limites de uso).
500	server_error	Erro do HotLearn. Tente de novo em instantes.

Limites de chamadas#

Onde	Limite
/api/v1/*	120 por minuto, por conexão (ou por chave pessoal)
/oauth/token	60 por minuto, por aplicativo e endereço de rede; 300 por minuto, por endereço
/oauth/revoke	30 por minuto
POST /api/v1/login-links	30 por minuto
GET /api/v1/openapi.json	60 por minuto
Vitrine pública (catalog:public, sem conta)	60 por minuto, por aplicativo
Respostas 401 (chave ausente ou inválida)	300 por minuto, por endereço de rede; depois disso, 429 para esse endereço

As respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining. Passou do limite: 429, com Retry-After em segundos.

Listas em páginas#

As listas vêm em páginas, com cursor:

{ "data": [ … ], "next_cursor": "eyJpZCI6MTJ9" }

• limit: de 1 a 50 (padrão 12);
• para a próxima página, mande cursor com o next_cursor recebido;
• next_cursor nulo quer dizer que a lista acabou.

Repetição segura (Idempotency-Key)#

As chamadas que gastam ou criam algo exigem o cabeçalho Idempotency-Key: POST /acquisitions, POST /materials/{id}/exports e POST /publications. Use um valor único por operação, como um UUID. Sem ele, 400 idempotency_key_required.

-H "Idempotency-Key: 6f1c2e8a-3b0d-4c55-9a7e-2f1d9b8c4a10"

• Repetiu a chamada com a mesma chave e os mesmos dados (por exemplo, depois de uma falha de rede): o HotLearn devolve a mesma resposta, sem fazer de novo, com o cabeçalho Idempotent-Replayed: true. Nada é cobrado duas vezes. Vale também para respostas de erro 4xx: elas ficam guardadas e voltam iguais.
• Mesma chave com outros dados: 422 idempotency_key_reused.
• Duas chamadas ao mesmo tempo com a mesma chave: a segunda recebe 409 idempotency_in_progress.
• Use uma chave nova a cada nova tentativa (por exemplo, depois de corrigir o pedido que deu erro).
• A chave vale por 24 horas, separada por conexão.
• Erros 5xx não ficam guardados: dá para tentar de novo com a mesma chave.