Documentation

Error Codes

CoffeeMail uses standard HTTP status codes combined with a machine-readable `code` field in the error envelope. The Node SDK types each status as a specialized class — you always receive the correct instance to inspect and handle.

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid payload. Check the schema and field types.
UNAUTHORIZED	401	API key missing, invalid or expired.
PAYMENT_REQUIRED	402	Plan limit reached or subscription suspended. Upgrade required.
FORBIDDEN	403	The key does not have permission for this resource.
NOT_FOUND	404	Resource not found or not accessible by your organization.
CONFLICT	409	Uniqueness conflict (e.g. domain already registered).
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded. Respect the Retry-After header.
INTERNAL_SERVER_ERROR	500	Internal platform failure. Try again in a few moments.

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);  }}

Retry policy

We recommend retries with exponential backoff and jitter for 5xx and 429 errors. Never retry 4xx errors (except 429) without first fixing the payload.