Erros

Todo erro da API v1 vem no mesmo envelope:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This token was not granted write access to this resource.",
    "details": { "required": ["write", "all"], "granted": ["read"] }
  }
}

Compare code, que é estável. A message é para gente e pode mudar. details aparece quando há o que detalhar.

Códigos

Status	code	Quando
400	VALIDATION_ERROR	corpo, filtro, ordenação ou cursor inválidos
401	INVALID_TOKEN, INVALID_AUDIENCE, INVALID_ISSUER, TOKEN_EXPIRED, TOKEN_REVOKED	problema no access token (Autenticação)
403	UNKNOWN_ORGANIZATION	a organização do token não está no Kadu
403	INSUFFICIENT_SCOPE	o token não tem o escopo da rota (Permissões)
403	USER_PERMISSION_DENIED, NOT_A_MEMBER	o papel da pessoa do token não permite
403	FEATURE_NOT_ENABLED	a Kobana não liberou essa operação para a organização
403	ENTITLEMENT_REQUIRED	disparo sem o Kadu no plano da organização
404	NOT_FOUND	o recurso não existe, foi removido ou é de outra organização
409	CONFLICT	conflito de estado (por exemplo, nome de ambiente já usado)
409	IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_REQUEST_IN_PROGRESS	ver Idempotência
413	PAYLOAD_TOO_LARGE	corpo acima de 1 MiB
422	MISSING_SECRETS	disparo com secrets exigidos sem valor no ambiente
422	ENVIRONMENT_REQUIRED	disparo sem ambiente válido
422	COST_LIMIT_REACHED	a organização atingiu o teto mensal de custo
429	RATE_LIMITED	limite de requisições (Limites)
500	INTERNAL_ERROR	falha nossa. A mensagem nunca traz detalhes internos.
503	AS_UNAVAILABLE	a verificação do token está indisponível. Tente de novo depois do Retry-After.

Além desses, uma rota pode devolver um código próprio, documentado na referência dela.

O que fazer

Status	Repetir?
4xx	Não: a mesma requisição vai falhar de novo. Corrija a causa.
409 IDEMPOTENCY_REQUEST_IN_PROGRESS	Sim, depois de alguns segundos, com a mesma chave.
429	Sim, depois do Retry-After.
5xx	Sim, com espera crescente e a mesma X-Idempotency-Key nas escritas.

O endpoint de disparo usa o mesmo envelope, com os códigos em minúsculas listados na página dele.