API

API error reference

How to interpret Problem Details, retryability, authentication failures, idempotency conflicts, rate limits, and webhook errors.

Last updated June 29, 2026

Problem Details

NewsletterIdea API errors use Problem Details with stable type links where possible. Do not parse internal exception text. Use status code, type, title, and documented recovery action.

Developer portal API docs Webhook guide API keys
{
  "type": "https://newsletteridea.com/problems/example",
  "title": "Request could not be completed",
  "status": 400
}

Status codes

  • 400Fix validation, unsupported format, malformed token, or unsafe query input.
  • 401Authentication failed; verify `X-Api-Key`, key status, and account access.
  • 403The key is valid but does not have permission for this operation.
  • 404The resource is missing or not owned by the authenticated account.
  • 409Idempotency conflict; reuse keys only for the same logical operation and body.
  • 429Rate limited; back off with jitter and preserve `Idempotency-Key` for retryable POSTs.
  • 503Service dependency unavailable; retryable only when the operation is idempotent.

Webhook and recovery errors

Webhook failures include invalid signature, replay protection failure, unsupported event type, endpoint validation failure, and delivery retry exhaustion. Rotate secrets from /account/webhooks and use the webhook guide for signing checks.