Reliability and errors

Implement safe retries, plain-text fallbacks, error handling, rate limits, and refund-aware reconciliation.

Idempotency

Same key + same body

Replays the stored result with no second charge.

Same key + changed body

Returns 409 idempotency_conflict.

Original still running

Returns 409 request_in_progress.

Problem responses

All API errors use application/problem+json. Branch on code, retain request_id, and show a merchant-safe message instead of exposing provider details.

application/problem+json

{
  "type": "https://www.lahjty.com/problems/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Too many requests. Retry after the indicated delay.",
  "request_id": "req_01jexample"
}

Fallback and retry policy

Use a client timeout appropriate to the endpoint; media can take longer than copy.
After an ambiguous timeout, replay the exact request with the same idempotency key.
Honor Retry-After for 429 and temporary provider errors.
Never block campaign sending on Lahjty. Preserve the merchant's plain text as the fallback.

Refunds

Provider and generation failures are refunded automatically under the endpoint contract. A partner-reported unchanged WhatsApp rejection becomes PENDING_VERIFICATION and does not change the balance. Lahjty applies the two-credit refund exactly once only after trusted Meta/provider evidence is verified. Edited submissions are recorded but are not candidates.