{
"error": {
"code": "organization_scope",
"message": "esta sessão não age nesta organização"
}
}
Trate pelo
code, nunca pela message. O código é contrato e não muda sem aviso; a
mensagem é diagnóstico para humano e pode ser reescrita a qualquer momento.Códigos
| Código | HTTP | O que aconteceu |
|---|---|---|
invalid_param | 400 | Parâmetro fora do contrato (um id que não é UUID, um limit que não é número) |
invalid_body | 400 | Corpo não é JSON válido, traz campo desconhecido, ou passa de 1 MiB |
unauthorized | 401 | Sessão ausente, inválida ou expirada |
invalid_credentials | 401 | E-mail ou senha errados — ou e-mail ainda não confirmado, de propósito igual |
invalid_signature | 401 | A assinatura do webhook não confere com o segredo da conexão |
organization_scope | 403 | A sessão é válida, mas não age no club pedido |
no_organization | 403 | A sessão não age em club nenhum |
forbidden | 403 | A sessão age no club, mas não o administra, e a operação exige isso |
email_verification_required | 403 | Já existe conta de aluno com este e-mail e a sessão não provou a caixa de entrada |
not_entitled | 403 | O aluno não tem direito a este curso |
not_released | 403 | O aluno tem direito, mas a agenda ainda não liberou esta aula; a data vem na mensagem |
club_not_found | 404 | O slug do club não existe |
connection_not_found | 404 | Token de webhook desconhecido, conexão desligada, ou plataforma diferente da conexão |
product_not_found, delivery_not_found, deliverable_not_found, course_not_found, module_not_found, lesson_not_found, student_not_found, enrollment_not_found, event_not_found | 404 | O recurso não existe neste club — de outro club responde igual |
link_expired | 410 | O link do e-mail já foi usado, expirou ou não existe — os três iguais |
slug_taken | 409 | Já existe curso (ou club) com este slug |
external_id_taken | 409 | Aquele id externo, naquela conexão e oferta, já aponta para outro produto |
club_without_classroom | 409 | O club ainda não tem endereço no classroom; não há para onde mandar link |
student_belongs_to_another_admin | 409 | A conta de aluno daquele e-mail é de outra pessoa que administra |
enrollment_already_active | 409 | Já existe outra matrícula ativa desta entrega para o aluno |
missing_field | 422 | Campo obrigatório ausente ou vazio |
weak_password | 422 | Senha abaixo do piso de 8 caracteres |
invalid_platform, invalid_secret, invalid_billing, invalid_scope, invalid_visibility, invalid_type, invalid_video_provider, invalid_release, invalid_access_days, invalid_open_window, invalid_slug | 422 | O campo veio, mas com valor que o contrato não aceita; a mensagem diz qual |
rate_limited | 429 | Teto de requisições atingido; respeite o Retry-After |
internal_error | 500 | Falha nossa; o detalhe está no rastreio, nunca no corpo |
not_configured | 501 | O ambiente não tem o que a operação precisa: provedor de autenticação, e-mail, chave de cifra |
rate_limit_unavailable | 503 | O contador de taxa caiu e esta rota falha fechada; tente em instantes |
Por que o 500 não explica nada
A resposta deinternal_error é sempre genérica, sem o erro real. Isso é deliberado: mensagem
de banco de dados conta a quem está do outro lado detalhes de esquema e de implementação. O
diagnóstico completo fica no nosso log e no rastreamento de erros, correlacionado pelo
X-Request-Id da resposta — se você abrir um chamado, é esse valor que encurta a investigação.