SendPromptly API Error Codes — Receipt and Result Endpoint Reference

Error Codes

This page documents the real error codes exposed by the current SendPromptly ingest surface. Focus on the receipt and result APIs first: if those two calls are stable, incident detection and reprocess will behave predictably.

Common API errors

Error code	HTTP status	Meaning	Common fix
`missing_idempotency_key`	400	The `Idempotency-Key` header is missing.	Add the header to every `receipt` and `result` request.
`validation_error`	422	Request payload failed endpoint validation.	Validate required fields like `provider`, `stripe_event_id`, `event_type`, and `status` before sending.
`unauthorized`	401	Missing or invalid bearer token.	Confirm the `Authorization: Bearer sk_...` header and rotate the key if needed.
`subscription_required`	402	The organization’s trial or subscription does not allow monitoring.	Restore billing access, then retry the same request with the same idempotency key.
`not_found`	404	`result` could not find the referenced event in the current project.	Make sure the matching `receipt` succeeded first and that you are using the right project key.
`missing_accept_header`	406	`Accept` header is required.	Send `Accept: application/json`.
`not_acceptable`	406	`Accept` does not allow JSON.	Explicitly allow `application/json` or `+json`.
`unsupported_media_type`	415	Request body is not JSON.	Send `Content-Type: application/json`.
`too_many_fields`	413	The payload exceeds the allowed top-level field count.	Trim debugging fields and keep the request contract focused.
`payload_too_large`	413	The request body exceeds the ingest size limit.	Remove oversized fields or keep large debugging data out of the payload.
`rate_limited`	429	Request rate exceeded the current per-project limit.	Back off and retry with jitter.
`internal_error`	500	SendPromptly failed while processing the request.	Retry with the same idempotency key after a short delay.

Field-level behavior to watch

receipt accepts provider, stripe_event_id or provider_event_id, event_type, effect_type, internal_reference, and occurred_at.
result requires one event identifier plus status: success|failed.
result can include error_code, error_message, and replay_id when a repair callback is reporting a reprocess attempt.

Debugging workflow

Confirm the app is calling POST /api/v1/receipt with the correct project key and JSON headers.
Confirm the response was 202 Accepted and returned an event_id.
Confirm the matching POST /api/v1/result uses the same event reference and a fresh idempotency key.
If result returns not_found, check the project key first, then the event identifier.
If repeated failures continue, use the incident timeline in the app to inspect the open event and any reprocess attempts.

Prevention checklist

Enforce request schema validation before your outbound API calls.
Use deterministic idempotency keys tied to the business action.
Keep request payloads small and metadata-first.
Alert on repeated 401, 402, 422, and 429 responses from your SendPromptly client.
Test one full failure-and-reprocess loop before enabling the flow in production.