Erros

As respostas de erro são JSON com pelo menos o campo error. Erros de validação (400) trazem campos extras explicando o que ajustar.

Status	Quando	Body
400	Parâmetro obrigatório ausente, tipo inválido, query/param desconhecido	{ "error": ..., ...detalhes }
401	x-api-key inválida (validação do handler)	{ "error": "nao autorizado" }
403	x-api-key ausente/incorreta barrada pelo API Gateway (antes do handler)	{ "message": "Forbidden" }
502	Athena falhou ou estourou o tempo limite (~55s)	{ "error": "Athena FAILED: ..." }
500	Erro interno inesperado	{ "error": "erro interno" }

Exemplos de 400

Parâmetro query ausente

{ "error": "parametro 'query' obrigatorio", "disponiveis": ["csps", "audits", "access_logs"] }

Query desconhecida

{ "error": "query desconhecida", "recebido": "foo", "disponiveis": ["csps", "audits", "access_logs"] }

Tipo inválido (esperava inteiro)

{ "error": "parametro invalido", "campo": "user_id", "esperado": "inteiro", "recebido": "abc" }

Parâmetro fora da whitelist

{ "error": "parametro desconhecido", "campo": "foo", "validos": ["action", "id", "user_id", "..."] }

Data/hora inválida

{ "error": "data/hora invalida", "campo": "fim", "esperado": "YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS", "recebido": "01/06/2026" }

Intervalo inválido (fim antes de inicio)

{ "error": "intervalo invalido", "motivo": "fim anterior a inicio" }

Intervalo muito grande (> 30 dias)

{ "error": "intervalo muito grande", "max_dias": 30, "informado_dias": 45 }

Cursor inválido

{ "error": "cursor invalido", "campo": "cursor" }

Diferença entre 401 e 403

• 403 Forbidden vem do API Gateway — header ausente ou chave que nem bate no usage plan. Você nem chega na Lambda.
• 401 nao autorizado vem do handler — chega na Lambda mas a revalidação do segredo falha.

Timeout (502)

A Lambda faz poll do Athena por até ~55s. Acima disso ela cancela a query e devolve 502 "query excedeu o tempo limite". No consumidor, use timeout de leitura maior que isso (ex.: 65s) para receber o erro em vez de cortar antes.