Skip to main content
Get started

Errors

The statuses the API really returns and the error envelope.

Envelope

Every error comes back in an error object with code, message and meta. The code is stable; the message is for people and may change; meta carries the field or limit involved.

400 VALIDATION_FAILED
{  "error": {    "code": "VALIDATION_FAILED",    "message": "O campo to precisa de pelo menos 1 destinatário",    "meta": { "field": "to" }  }}

Codes

HTTPcodeWhen it happens
400VALIDATION_FAILEDA body or query field is invalid; meta says which.
400INVALID_RECIPIENTThe recipient is not a valid address.
401UNAUTHORIZEDMissing, invalid or revoked key.
409DOMAIN_NOT_VERIFIEDThe sender domain has not passed DNS verification yet.
409EMAIL_NOT_CANCELLABLEOnly scheduled emails not yet sent can be cancelled.
422INVALID_FROM_DOMAINThe from address uses a domain that does not belong to the organization.
422SENDER_NOT_VERIFIEDThe single sender has not confirmed the email yet.
429PLAN_QUOTA_EXCEEDEDThe plan quota ran out in the cycle; enable overage or change plans.
429RATE_LIMIT_EXCEEDEDToo many requests; wait the retry-after time.
500TEMPLATE_RENDER_ERRORThe template did not render with the variables sent.
Keep the x-request-id from the response: support finds the request with it right away.

In the SDKs

The SDKs do not throw on API errors: the error comes typed in the result, with code, status and requestId.

Node.js
const { data, error } = await coffeemail.emails.send(payload); if (error instanceof ValidationError) return showFieldErrors(error.details);if (error instanceof RateLimitError) return retryLater(error);if (error) throw error; console.log(data.id, data.status);
Go
_, err := client.Domains.Get(ctx, id)if errors.Is(err, coffeemail.ErrNotFound) {	return nil} var apiErr *coffeemail.Errorif errors.As(err, &apiErr) {	log.Printf("status=%d code=%s requestId=%s", apiErr.Status, apiErr.Code, apiErr.RequestID)}