API Error Codes & Meanings — SendPromptly Troubleshooting

Error Codes

This page documents common API and delivery errors you may see while integrating SendPromptly. For each error, focus on two outcomes: restore delivery quickly and prevent repeated failures.

API errors

Error code	HTTP status	Meaning	Common fix
`validation_error`	400	Request payload failed schema or required fields.	Validate `event_key`, `recipient`, and payload shape before send.
`unauthorized`	401	Missing or invalid bearer token.	Confirm token format and environment scope. Rotate if needed.
`payment_required`	402	Billing state prevents ingestion.	Resolve billing state, then retry with the same idempotency key.
`quota_exceeded`	403	Plan usage limit reached.	Upgrade plan or add capacity, then resume ingestion.
`idempotency_conflict`	409	Same idempotency key used with different request body.	Generate deterministic keys per unique business event.
`rate_limited`	429	Request rate exceeded current limit.	Back off and retry with jitter; smooth burst traffic.

Delivery errors

Error code	Typical cause	Recovery action
`template_inactive`	No active template for the event key.	Activate or publish the correct template version.
`provider_not_configured`	Email provider or endpoint settings missing.	Complete provider configuration in the project environment.
`placeholder_missing_in_context`	Template variable not present in payload.	Add missing payload fields or fallback-safe template logic.
`send_error`	Downstream provider or endpoint failure.	Retry with backoff; inspect destination response details.
`scheduled_cancelled`	Scheduled run cancelled before execution.	Review cancellation path and scheduling rules.

Debugging workflow

Find the failing ingestion request or delivery run in logs.
Confirm whether the error is integration, configuration, or transient infrastructure.
Apply the smallest safe fix (payload, token, template, or provider setting).
Replay using the original business event id where possible.

Prevention checklist

Enforce request schema validation before API calls.
Use deterministic idempotency keys.
Track 4xx, 5xx, and retry metrics by event key.
Alert on repeated template_inactive and provider_not_configured failures.

For webhook-specific troubleshooting, see Webhook Delivery Logs and Debugging.