Documentation

Códigos de error

CoffeeMail usa códigos HTTP estándar combinados con un campo `code` legible por máquina en el sobre de error. El SDK de Node tipifica cada estado como una clase especializada siempre recibes la instancia correcta para inspeccionar y manejar.

Código	HTTP	Descripción
VALIDATION_ERROR	400	Payload inválido. Verifica el esquema y los tipos de los campos.
UNAUTHORIZED	401	API Key ausente, inválida o expirada.
PAYMENT_REQUIRED	402	Límite del plan alcanzado o suscripción suspendida. Upgrade requerido.
FORBIDDEN	403	La clave no tiene permiso para este recurso.
NOT_FOUND	404	Recurso no encontrado o no accesible por tu organización.
CONFLICT	409	Conflicto de unicidad (p. ej. dominio ya registrado).
RATE_LIMIT_EXCEEDED	429	Rate limit excedido. Respeta el header Retry-After.
INTERNAL_SERVER_ERROR	500	Fallo interno de la plataforma. Intenta de nuevo en unos 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 reintentos

Recomendamos reintentos con backoff exponencial y jitter para errores 5xx y 429. Nunca reintentes errores 4xx (excepto 429) sin antes corregir el payload.