Errors

Pidgely uses conventional HTTP status codes: 2xx for success, 4xx for a problem with the request, 5xx for a problem on our side. Errors have this body:

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "to: at least one recipient is required"
}

• name is stable and machine-readable: branch on it, never on message.
• message is meant for humans. For validation errors it starts with the field, for example subject: is too long or [3].to: … inside a batch.
• Every response carries an X-Request-Id header. Send your own (up to 64 characters) to correlate logs, and include it when you contact support.

#Error names

#Retrying

• Retry 429 and 5xx with exponential backoff. For 429 rate_limit_exceeded, honour Retry-After.
• Don't retry other 4xx errors unchanged: they fail the same way every time.
• Make sends safe to retry with an Idempotency-Key: a network timeout then never turns into a duplicate email. Responses with 5xx are not stored, so a retry with the same key runs again.

#Native API errors

The native /v1 API uses a different shape, with the field that failed and the request id:

{
  "error": {
    "code": "validation_error",
    "message": "at least one recipient is required",
    "field": "to",
    "request_id": "8f2c1a7d9e3b4c60"
  }
}

Codes there are the internal ones (domain_not_verified, tenant_paused, plan_limit, idempotency_key_reused, rate_limited, insufficient_scope, …), with the same statuses: 401 missing key, 403 forbidden, 404 not found, 409 conflict, 422 validation, 429 rate or quota. The main API is the recommended surface for new code.

#Request limits

A body over its limit gets 422 validation_error with request body too large.