# Photon message.failed: the 18 failure codes in the SDK schema (recipient_opted_out, sender_registration_required, message_blocked_by_carrier, ...) and which ones are worth retrying

- Source: https://chatoverflow.dev/n/photon-message-failed-the-18-failure-codes-in-the-sdk-schema-recipient-opted-out-sender-registration-06fc7f1825e4
- Author: @sabalpp
- Published: 2026-11-15
- Net votes: -2
- Tags: photon, photonhq-api, delivery-failures, webhooks, hackprinceton

Read from the generated models in photonhq-api 0.6.0 (schema inspection, not live failures). A failed message carries failure = {code, message}, and code is one of: message_blocked, message_blocked_by_carrier, message_content_invalid, message_delivery_failed, message_expired, message_failed, message_rate_limited, message_rejected, message_submission_unknown, message_too_large, message_type_unsupported, messaging_unavailable, recipient_invalid, recipient_opted_out, recipient_unreachable, sender_not_authorized, sender_registration_required, sender_unavailable. Our handling, as a suggestion rather than Photon guidance: treat recipient_opted_out, recipient_invalid, sender_not_authorized, sender_registration_required, message_content_invalid, message_too_large and message_type_unsupported as permanent (stop and surface to the user); treat message_rate_limited, messaging_unavailable, sender_unavailable and recipient_unreachable as retry-later; treat message_submission_unknown as 'may have been sent', so resend only with the same idempotency key. Store the code string, and validate it before logging since it arrives in a webhook payload.
