uloggd

code é estável e existe para ser comparado. message é para quem lê um log e não é contrato: pode ser reescrito a qualquer momento.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not hold library.write.",
    "scope": "library.write"
  }
}

Código	Status	Significa
`unauthorized`	401	A requisição não trouxe identidade nenhuma: nem chave, nem sessão desta origem.
`forbidden`	403	A identidade está certa e a regra recusou mesmo assim: um bloqueio, uma conta privada, um espaço de comentários fechado. Quando a recusa é uma dessas, a mensagem diz qual.
`invalid_key`	401	Desconhecida, revogada ou expirada. As três não são distinguidas.
`insufficient_scope`	403	A chave não tem o escopo, que vem nomeado no corpo.
`not_found`	404	Não existe, ou não é algo que o dono possa ver.
`invalid_request`	400	Falta um campo ou ele não é aceito. A mensagem diz qual.
`conflict`	409	Isso já existe.
`rate_limited`	429	Traz retry_after em segundos.
`internal`	500	Algo falhou aqui. Nada sobre o schema é dito.
`unavailable`	503	Hoje só em GET /api/v1/arcade/jwks, com reason identity_unavailable: o servidor ainda não tem as chaves que assinam a identidade do Arcade. Tente de novo mais tarde.

Outros membros

Ao lado de code e message, uma recusa pode trazer:

reason: uma palavra para agir, mais precisa que o code, nas recusas do Arcade e em algumas da conta, como reauthentication_required e mfa_required. Um cliente que encontra uma que não conhece age pelo code.
field: o campo recusado, com invalid_request.
detail: uma causa mais fina, como too_large num media_invalid.
retry_after: quantos segundos esperar, com rate_limited.
scope: o escopo que faltou, com insufficient_scope.
check: o resultado da verificação de URL, quando enviar um lançamento do Arcade ou torná-lo ao vivo é recusado.
second_factor: com reauthentication_required, nas rotas que aceitam um código no lugar de entrar de novo, se um código da verificação em duas etapas serve.

As recusas do Arcade, com cada reason, estão na tabela de recusas do Arcade.

De onde vem uma recusa

A maioria das recusas é do banco, não do handler. Uma constraint, uma coluna não nula, um gatilho de limite ou uma política de linha levanta o erro, e esse erro é traduzido para o formato acima.

Só as recusas levantadas de propósito levam a mensagem para fora. Qualquer outra responde internal sem dizer mais nada, porque mensagem de erro imprevista é descrição do schema.

404 not_found cobre dois casos de propósito: o recurso não existe, e o recurso existe mas o dono da chave não pode vê-lo. Distinguir os dois seria um jeito de perguntar se a lista privada de alguém existe.

code é estável e existe para ser comparado. message é para quem lê um log e não é contrato: pode ser reescrito a qualquer momento.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not hold library.write.",
    "scope": "library.write"
  }
}

Código	Status	Significa
`unauthorized`	401	A requisição não trouxe identidade nenhuma: nem chave, nem sessão desta origem.
`forbidden`	403	A identidade está certa e a regra recusou mesmo assim: um bloqueio, uma conta privada, um espaço de comentários fechado. Quando a recusa é uma dessas, a mensagem diz qual.
`invalid_key`	401	Desconhecida, revogada ou expirada. As três não são distinguidas.
`insufficient_scope`	403	A chave não tem o escopo, que vem nomeado no corpo.
`not_found`	404	Não existe, ou não é algo que o dono possa ver.
`invalid_request`	400	Falta um campo ou ele não é aceito. A mensagem diz qual.
`conflict`	409	Isso já existe.
`rate_limited`	429	Traz retry_after em segundos.
`internal`	500	Algo falhou aqui. Nada sobre o schema é dito.
`unavailable`	503	Hoje só em GET /api/v1/arcade/jwks, com reason identity_unavailable: o servidor ainda não tem as chaves que assinam a identidade do Arcade. Tente de novo mais tarde.

Outros membros

Ao lado de code e message, uma recusa pode trazer:

reason: uma palavra para agir, mais precisa que o code, nas recusas do Arcade e em algumas da conta, como reauthentication_required e mfa_required. Um cliente que encontra uma que não conhece age pelo code.
field: o campo recusado, com invalid_request.
detail: uma causa mais fina, como too_large num media_invalid.
retry_after: quantos segundos esperar, com rate_limited.
scope: o escopo que faltou, com insufficient_scope.
check: o resultado da verificação de URL, quando enviar um lançamento do Arcade ou torná-lo ao vivo é recusado.
second_factor: com reauthentication_required, nas rotas que aceitam um código no lugar de entrar de novo, se um código da verificação em duas etapas serve.

As recusas do Arcade, com cada reason, estão na tabela de recusas do Arcade.

De onde vem uma recusa

A maioria das recusas é do banco, não do handler. Uma constraint, uma coluna não nula, um gatilho de limite ou uma política de linha levanta o erro, e esse erro é traduzido para o formato acima.

Só as recusas levantadas de propósito levam a mensagem para fora. Qualquer outra responde internal sem dizer mais nada, porque mensagem de erro imprevista é descrição do schema.

Erros

Outros membros

De onde vem uma recusa

Nesta página

Erros

Outros membros

De onde vem uma recusa

Nesta página