Documentation

Códigos de erro

A CoffeeMail usa códigos HTTP padrão combinados com um campo `code` legível por máquina no envelope de erro. O SDK Node tipa cada status como uma classe especializada você sempre recebe a instância correta para inspecionar e tratar.

Código	HTTP	Descrição
VALIDATION_ERROR	400	Payload inválido. Verifique o schema e os tipos dos campos.
UNAUTHORIZED	401	API Key ausente, inválida ou expirada.
PAYMENT_REQUIRED	402	Limite do plano atingido ou assinatura suspensa. Faça upgrade.
FORBIDDEN	403	A chave não tem permissão para este recurso.
NOT_FOUND	404	Recurso não encontrado ou inacessível pela sua organização.
CONFLICT	409	Conflito de unicidade (ex: domínio já cadastrado).
RATE_LIMIT_EXCEEDED	429	Rate limit excedido. Respeite o header Retry-After.
INTERNAL_SERVER_ERROR	500	Falha interna da plataforma. Tente novamente em alguns instantes.

Exemplo de payload

JSONjson

{  "error": {    "code": "VALIDATION_ERROR",    "message": "O campo 'from' deve ser um e-mail válido.",    "details": { "field": "from" }  }}

Tratamento com o SDK Node

O SDK mapeia cada código acima para uma classe especializada exportada de @coffeemail/node:

handle-errors.ts

import {  CoffeeMail,  ValidationError,  AuthenticationError,  PaymentRequiredError,  ForbiddenError,  NotFoundError,  ConflictError,  RateLimitError,  InternalServerError,} from '@coffeemail/node'; const coffeemail = new CoffeeMail(process.env.COFFEEMAIL_API_KEY);const { error } = await coffeemail.emails.send({ /* ... */ }); if (error) {  switch (error.code) {    case 'VALIDATION_ERROR':      console.error('Payload inválido:', error.details);      break;    case 'UNAUTHORIZED':      console.error('API key inválida.');      break;    case 'RATE_LIMIT_EXCEEDED':      // RateLimitError expõe retryAfterSeconds quando presente.      console.error('Rate limit. Tente em', error.retryAfterSeconds, 's');      break;    case 'PAYMENT_REQUIRED':      console.error('Limite do plano. Faça upgrade.');      break;    default:      console.error(error.status, error.message);  }}

Política de retentativas

Recomendamos retries com backoff exponencial e jitter para erros 5xx e 429. Nunca retentative erros 4xx (exceto 429) sem antes corrigir o payload.