Erros

A maioria dos endpoints devolve erros neste formato:

{ "statusCode": 401, "message": "mensagem descritiva do erro", "error": "Unauthorized" }

Erros de validação (400) incluem também um objecto errors, um por campo inválido:

{
  "statusCode": 400,
  "message": "Erro de validação",
  "errors": { "to": "to é obrigatório" }
}

Limites excedidos (429) usam um formato próprio — ver Limites de envio abaixo.

Códigos de estado

Código	Significado	Quando acontece
`200`	OK	Leitura bem-sucedida (ex: URL de download gerada)
`201`	Criado	Email enviado, ou URL de upload gerada
`400`	Pedido inválido	Campo obrigatório em falta ou inválido
`401`	Não autorizado	API key em falta, inválida ou revogada
`403`	Proibido	Organização não activa, ou domínio do `from` não verificado/não pertence à tua organização
`404`	Não encontrado	Anexo inexistente, ou pertence a outra organização
`422`	Não processável	Email rejeitado no envio
`429`	Demasiados pedidos	Limite de envio excedido (por segundo ou diário)
`500`	Erro interno	Falha inesperada no servidor
`503`	Serviço indisponível	Envio temporariamente indisponível

Um 401 acontece sempre que a API key está em falta, é inválida, ou foi revogada — nunca assumas que uma chave que funcionou ontem continua válida hoje sem tratar este caso no teu código.

Um 403 em POST /v1/emails significa que o domínio do from não está verificado, ou não pertence à tua organização — confirma o estado em Settings → Domains no workspace.

Limites de envio

Cada organização tem um plano com um limite diário e um limite por segundo. Ultrapassar qualquer um devolve 429:

429 Too Many Requests
{ "error": "rate_limit_exceeded", "retry_after_seconds": 1 }

429 Too Many Requests
{ "error": "daily_limit_exceeded" }

`error`	Significado
`rate_limit_exceeded`	Ultrapassaste o número de emails por segundo do teu plano. Vem com `retry_after_seconds`.
`daily_limit_exceeded`	Ultrapassaste o número de emails por dia do teu plano. Reseta à meia-noite UTC.

Começar

Guias

Essenciais

Códigos de estado

Limites de envio

​Códigos de estado

​Limites de envio

Códigos de estado

Limites de envio