Errors

Error responses, what each one means, and which ones to retry.

Successful requests return 2xx. Errors return a JSON body with the HTTP status, a stable machine-readable name and a human-readable message:

Response 422

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Invalid `to` field. The email address needs to follow the `email@example.com` or `Name <email@example.com>` format."
}

Branch on name; messages may be reworded over time.

Error names

Status	name	Meaning	Retry?
400	`invalid_idempotency_key`	The Idempotency-Key is not 1 to 256 characters.	No
401	`missing_api_key`	No API key in the request.	No
401	`restricted_api_key`	A sending-access key called an endpoint that needs full access.	No
403	`invalid_api_key`	The key is unknown, revoked, or the account is suspended.	No
403	`invalid_from_address`	The from address is not an active sender on a verified domain, or the key is limited to another domain.	No
403	`plan_inactive`	Your plan does not allow adding contacts.	No
404	`not_found`	The email, template or endpoint does not exist in your account.	No
409	`invalid_idempotent_request`	The Idempotency-Key was already used with a different body.	No
409	`concurrent_idempotent_requests`	A request with the same key is still running.	Yes, shortly
422	`missing_required_field`	A required field is missing.	No
422	`validation_error`	A field is invalid, or a template variable is missing.	No
413	`validation_error`	The request body is larger than 10 MB.	No
422	`invalid_attachment`	An attachment is too large, not base64, or of a blocked type.	No
429	`rate_limit_exceeded`	More requests per second than your plan allows.	Yes, after retry-after
429	`monthly_quota_exceeded`	The plan’s monthly email allowance is used up, or the plan is not active.	No
500	`application_error`	Something went wrong on Cresca’s side.	Yes, with backoff
503	`service_unavailable`	Sending is temporarily unavailable.	Yes, with backoff

Retry 429, 5xx, timeouts and network errors with exponential backoff and jitter, and send an Idempotency-Key so retries never duplicate an email. Do not retry other 4xx errors: the same request will fail the same way.

Error names

Retry strategy