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

# Troubleshooting

> Common problems with the Inboxapp API and how to fix them

Every error carries a `requestId`. Include it when you contact support.

## Authentication

<AccordionGroup>
  <Accordion title="401 unauthorized on every request">
    Check the header is exactly `Authorization: Bearer <token>`, with no quotes
    or trailing newline. A deleted token fails the same way: create a new one in
    **Settings → API**.
  </Accordion>

  <Accordion title="403 workspaceLocked">
    The team's billing is paused or past due, or its trial ended. Reads and writes
    both fail until it is resolved in Inboxapp.
  </Accordion>
</AccordionGroup>

## Sending

<AccordionGroup>
  <Accordion title="403 planRequired when sending">
    A `profile` target reached someone who isn't one of your contacts, which needs
    the Advanced API add-on. Sending to a `thread` or `contact` target doesn't.
  </Accordion>

  <Accordion title="409 accountLinkDisconnected">
    The account isn't `active`. `details.status` is `offline` when it must be
    reconnected in Inboxapp, or `paused` for the reasons in the account link's
    `pauseReasons`.
  </Accordion>

  <Accordion title="422 recipientUnavailable">
    The platform won't let this account message that person: they may not accept
    messages from accounts they don't follow, or the account no longer exists.
    `details.reason` says which. Retrying won't help.
  </Accordion>

  <Accordion title="502 sendUnconfirmed">
    Inboxapp couldn't confirm the platform accepted the message. It may have been
    delivered. Don't resend it. Read `details.messageId` later to see how it
    settled.
  </Accordion>

  <Accordion title="A retry sent the message twice">
    Send an `Idempotency-Key` header and reuse the same key on every retry of the
    same message. See [Send safely](/v2/guides/messages#send-safely).
  </Accordion>
</AccordionGroup>

## Reading

<AccordionGroup>
  <Accordion title="GET /contacts returns an empty list">
    `platform` is required, with `platformId` or `username`. Pass `username`
    without its `@`. An empty list means your team has no record of that person
    yet, not that they don't exist on the platform.
  </Accordion>

  <Accordion title="A thread is missing from GET /threads">
    The default folder is `inbox`, which leaves out archived threads and requests.
    Pass `folder=all`.
  </Accordion>

  <Accordion title="400 invalidRequest on a filter with brackets">
    Filters don't take bracket notation. Repeat the key instead: `tag=a&tag=b`.
    See [Query parameters](/v2/reference/query-parameters).
  </Accordion>

  <Accordion title="400 invalidCursor">
    A cursor only works with the filters it was issued for. Restart from the first
    page after changing a filter.
  </Accordion>

  <Accordion title="An attachment URL stopped working">
    Media URLs expire at `expiresAt`. Get a fresh one from `GET /messages/   {messageId}/attachments/{index}`.
  </Accordion>
</AccordionGroup>

## Capabilities

<AccordionGroup>
  <Accordion title="422 capabilityNotSupported">
    The account link can't do this. Check its `capabilities` before calling, and
    [Platforms and capabilities](/v2/platforms) for what the platform allows.
  </Accordion>

  <Accordion title="422 mutationWindowClosed on an edit">
    The platform only allows edits for a time after sending. The window is in `GET
          /platforms`, under `mutationWindows`.
  </Accordion>

  <Accordion title="403 platformNotAvailable">
    The thread or contact is on a platform that isn't enabled for your team. `GET
          /platforms` lists the ones that are.
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="Events are missing">
    Each event is delivered once, with no retries. Read what you missed from `GET
          /events?afterSeq=…`. See [Replay missed
    events](/v2/webhooks/overview#replay-missed-events).
  </Accordion>

  <Accordion title="The payload has no message or thread in it">
    v2 events are thin: they name the object and carry only what changed. Read
    `object.url` for the current state.
  </Accordion>

  <Accordion title="Signature verification fails">
    Verify against the raw request body, before any JSON parsing. See [Verifying
    webhook signatures](/v2/webhooks/verifying-signatures).
  </Accordion>
</AccordionGroup>

## Still stuck

Email [support@inboxapp.com](mailto:support@inboxapp.com) with the `requestId`, the endpoint and the time of the request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.