API Error Codes & Troubleshooting

The envelope

Every failure returns the same three fields, at every status. error is stable and safe to branch on; message is written for a human reading a log and may change.

Some errors add fields — a rejected batch item carries its index, a throttled account carries the rate that caused it. Treat anything beyond the three below as advisory.

{
  "error": "recipient_not_allowlisted",
  "message": "Key allowlist is [@example.com]. Recipient is outside it.",
  "docs": "https://www.sadasend.com/docs/errors#recipient_not_allowlisted"
}

Authentication and scope

Sending

The codes worth handling explicitly. A send that fails with any of these has not been queued and will not be retried for you.

Remediating autonomous guardrail & security errors

Detailed diagnostic breakdowns and resolution recipes for the built-in safety controls and autonomous agent error conditions.

Outbound DLP secret detection (dlp_secret_detected & dlp_violation)

Autonomous AI agents running code, analyzing data, or querying internal APIs frequently handle sensitive runtime credentials (API keys, database strings, tokens, private keys). If an agent dumps debug context or runtime memory into an outgoing email, the Outbound DLP scanner intercepts it before network transmission.

The scanner inspects subject, text, and raw html (including HTML attributes, data properties, URLs, and comments) for:

• Provider API Secrets: Anthropic Claude (sk-ant-api03-...), OpenAI (sk-...), AWS Access Key IDs (AKIA...), GitHub PATs (ghp_... and github_pat_...), Stripe live keys (sk_live_..., rk_live_...), Slack bot tokens (xoxb-...), Google Cloud, SendGrid, and Resend.

• Cryptographic Private Keys: RSA, EC, OpenSSH, DSA, and encrypted private key blocks (-----BEGIN ... PRIVATE KEY-----).

• Payment Card Industry (PCI) PII: Visa, Mastercard, American Express, and Discover formats verified via Luhn mod 10 checksum validation to eliminate false positives on serial numbers.

• Government IDs: US Social Security Numbers (SSNs) with valid area/group structure (rejecting 000, 666, and 900+ series).

When intercepted, the API returns HTTP 422 with a cryptographically safe redacted preview and the exact location where the secret was found:

• Step 1 — Identify the leaked variable: Check location (subject, text, or html) and search your template or agent prompt for the token prefix shown in preview.
• Step 2 — Scrub runtime environment variables: Ensure debug variables (process.env, os.environ, API client responses) are not serialized into the prompt context or email body template.
• Step 3 — Diagnostic Opt-Out: If you are intentionally running internal diagnostic tests or penetration tests, pass "dlp": false in the request body to bypass the pattern matcher.

{
  "error": "dlp_secret_detected",
  "message": "Outbound DLP scanner blocked email containing exposed Anthropic API token",
  "preview": "sk-ant***890",
  "location": "html",
  "docs": "https://www.sadasend.com/docs/errors#dlp_secret_detected"
}

Autonomous loop circuit breaker (duplicate_content_loop_detected)

Autonomous AI agents operating in agentic tool-use loops can enter infinite execution cycles due to retry bugs, unhandled exceptions, or looping reasoning models. Repeatedly dispatching identical emails burns customer quotas and damages sender reputation.

SadaSend computes a deterministic rolling SHA-256 fingerprint over sorted recipients, subject, and normalized body text with a 5-minute (300-second) sliding window:

• Transparent Deduplication: If an identical email is re-sent to the same recipient within 5 minutes, SadaSend transparently deduplicates the send, returning { ok: true, deduplicated: true } and echoing the original messageId without consuming monthly quota or queuing duplicate spam.

• Circuit Breaker Trip: If rapid runaway bursts continue beyond the deduplication threshold, HTTP 429 duplicate_content_loop_detected is returned.

• Broadcast Safety: The fingerprint binds strictly to the recipient set. Sending identical newsletters or transactional receipts to different customers is never deduplicated.

• Fix: Investigate your agent’s termination condition or exception handling. Ensure your agent checks for existing delivery IDs before re-issuing tool calls.

{
  "error": "duplicate_content_loop_detected",
  "message": "Circuit breaker tripped: autonomous loop detected after matching 5 identical body content hashes within a 5-minute rolling window",
  "docs": "https://www.sadasend.com/docs/errors#duplicate_content_loop_detected"
}

Inbound prompt injection threat (prompt_injection_flagged)

When autonomous agents process incoming emails, adversaries can embed prompt injections, system prompt overrides, or jailbreak instructions within reply text.

SadaSend runs edge heuristic classifiers on inbound emails. If the risk score exceeds 0.85, the payload is flagged with HTTP 422 prompt_injection_flagged:

• Fix: Ingest inbound emails through POST /inbound/parse to extract token-efficient sanitized Markdown (cleanMarkdown) stripped of quoted chains and mobile signatures, and evaluate security.quarantineRecommended before passing text to LLM context.

{
  "error": "prompt_injection_flagged",
  "message": "Inbound email classified with high prompt injection score (>0.85) containing jailbreak instructions or delimiter overrides",
  "docs": "https://www.sadasend.com/docs/errors#prompt_injection_flagged"
}

Batches, logs and message actions

Domains, keys and approvals

Webhooks

Templates and suppressions

Account, team and support

These come from the dashboard-facing routes rather than from an integration, but they use the same envelope.

Free tools and sign-in

The tool checks are unauthenticated and rate-limited by source. The sign-in codes surface in the browser rather than in an integration.