> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pushctl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel troubleshooting

> Resolve configuration, recipient routing, response, timeout, and duplicate-send issues.

<AccordionGroup>
  <Accordion title="Pushctl is not configured">Set a non-empty `PUSHCTL_TOKEN`. Set `PUSHCTL_URL` only when using a different service origin. Clear cached configuration after changing environment values.</Accordion>
  <Accordion title="The API returns 403">Create a token with **Server send** or **Full access**. The request requires `notifications:send`.</Accordion>
  <Accordion title="Nothing is sent and no exception occurs">The notifiable route returned `null`, an empty string, or an empty array. Confirm `routeNotificationForPushctl` returns external user IDs.</Accordion>
  <Accordion title="toPushctl errors">The notification must define `toPushctl(object $notifiable): PushctlMessage` and include `PushctlChannel::class` in `via`.</Accordion>
  <Accordion title="The request times out">Increase `PUSHCTL_TIMEOUT` from its 10-second default and queue the notification. Also check outbound HTTPS connectivity.</Accordion>
  <Accordion title="A retry sends duplicates">Set a stable `idempotencyKey` on the message before dispatching queued work.</Accordion>
  <Accordion title="The API returns 422">Check recipient count and message limits: at least one and at most 500 recipients, a title/body/data value, valid URLs, TTL, and platform option types.</Accordion>
</AccordionGroup>

<Info>HTTP failures are rethrown by Laravel's HTTP client. Catch or let your queue worker retry according to the failure policy for your application.</Info>