Diagnose by status and stable code

Preserve X-Request-Id, operation ID and status. Never log the API key, recipient URL, contact, proof image or raw webhook body. Some endpoints return a structured code, others return validation errors or an empty 401/403/404. Do not assume every error has the same JSON shape, and never branch on translated message text.

Code or status	Likely cause	Retry and corrective action
401	Missing, malformed, revoked or expired credential	Correct the credential; do not retry unchanged
403	Missing scope or account permission	Check operation scope and environment; refresh credentials after configuration changes
404	Wrong ID/environment or expired/invalid capability	Check the authenticated canonical read and environment
429	Rate limit/quota	Respect Retry-After; exponential backoff with jitter
5xx / transport failure	Temporary service/network failure	Reuse exact IDs and payload, use bounded retries, and inspect canonical state after an uncertain outcome
returns_paused	Return writes are temporarily unavailable	Retry later with the same IDs; reads remain available
idempotency_key_invalid	Missing/oversized creation key	Provide a stable nonempty key, maximum 160 characters
idempotency_conflict	Reused key for a different operation	Recover the original request or use a key for a genuinely new operation
event_id_invalid	Missing/empty UUID	Generate and persist one UUID per event
occurred_at_invalid	Future event time	Correct clock/timestamp; preserve actual occurrence time
return_not_eligible	Outbound state does not allow this return type	Customer return needs Delivered; failed-delivery RTS needs DeliveryAttempted
return_state_conflict	Invalid transition, proof dependency or conflicting event	Read canonical state and proof requirements; correct before retry
return_conflict	Concurrent return/identifier constraint	Read current return; do not create duplicate physical work
return_origin_invalid, return_destination_invalid	Missing/invalid snapshot	Supply valid confirmed address fields and coordinates
return_event_invalid	Invalid event input	Correct input using API reference
return_pickup_confirmation_not_allowed	Pickup access not allowed in current state	Inspect authorization/handover state before issuing a new link
return_proof_asset_missing	Reference does not point to uploaded return asset	Upload PNG first with matching return/proof/kind; use returned reference
return_proof_invalid, proof_image_invalid	Invalid image or proof fields	Correct method, purpose, dimensions, size and timestamp
return_proof_conflict	Proof UUID reused with different content	Retry identical proof; never overwrite immutable evidence
return_destination_required	RTS policy needs a destination	Provide the agreed sender/merchant destination

Common integration issues

Copied key starts with [object Object]: recopy the credential from the console. A key contains no icon, markup or trailing display text. Configure the full raw value.

Delivery status has not advanced after proof submission: inspect proof synchronization. The delivery:proof scope is separate from delivery:events. A failed proof blocks the dependent completion event. Fix the configuration and retry the original operation with the same identifiers.

My email matches but the recipient link fails: verify that the canonical shipment contact is correct and the account contact is verified. A contact used only for address confirmation does not change shipment ownership. Public tracking proves progress, not recipient authorization.

No return option is available: the delivery must be linked and canonically Delivered before a customer return can begin.

Return proof URL rejected: upload a real PNG through the return asset API. A text signature or arbitrary merchant URL does not satisfy this contract.

Webhook signature fails: preserve raw bytes, verify the correct subscription secret, check timestamp freshness and avoid JSON reserialization. See the webhook cookbook.