API error codes

When an API request fails, Buttondown returns a structured error response containing an error code and a human-readable message. This page provides a comprehensive reference for all error codes you might encounter. (Be sure to also check out the status code of the response!)

Errors tied to a specific error code follow this consistent format:

{
  "code": "email_invalid",
  "detail": "The email address provided is not valid.",
  "metadata": {
    "field": "email_address"
  }
}

Requests that fail schema validation — for example, sending an unknown field, an over-long value, or a malformed identifier — instead return a 422 with a detail array containing one entry per invalid field:

{
  "detail": [
    {
      "type": "extra_forbidden",
      "loc": ["body", "payload", "unexpected_field"],
      "msg": "Extra inputs are not permitted"
    }
  ]
}

Each entry's type names the validation failure (common values include extra_forbidden, missing, string_too_long, and string_pattern_mismatch) and loc points to the offending field. Sending only the documented fields, within their documented limits, avoids these.

Error codes specific to each API endpoint are now documented directly on the individual endpoint pages. When viewing an endpoint's documentation, you'll find a dedicated "Error codes" section that lists all possible error codes for that endpoint, along with their descriptions and how to fix them.

For example:

• Creating subscribers
• Creating emails
• Listing subscribers

This approach makes it easier to find the relevant error codes when working with a specific endpoint.

1. Always check the HTTP status code first - This gives you the general category of error
2. Parse the error code - Use the specific error code for programmatic handling
3. Check metadata fields - Additional context may be provided in the metadata object
4. Implement retry logic - For 429 and 5xx errors, implement exponential backoff
5. Validate locally - Reduce API errors by validating data before sending requests