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

# Troubleshooting

> Common codes and situations when working with the do-not-contact list.

<Tip>
  Most issues fall into three categories: **invalid identity**, **key scope**, or **suppressed recipient at send time**.
</Tip>

## In brief

* Suppression does **not spend credit** or call the provider — the send stops with `RECIPIENT_SUPPRESSED`.
* **Transient** provider failures do not create suppression automatically.
* Permanent bounces, complaints, and `STOP` are durable signals and may create an entry on their own.

***

## Codes in the suppressions API

| Code                        | What it means                                            | What to do                                                           |
| --------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| `INVALID_SUPPRESSION_TYPE`  | `type` outside `email`, `phone`, `telegram`, `instagram` | Fix the type                                                         |
| `INVALID_SUPPRESSION_VALUE` | Value failed normalization                               | See [Normalization](/en/suppressions-api/como-funciona/normalizacao) |
| `INVALID_BATCH_SIZE`        | More than 100 items in batch                             | Split into multiple calls                                            |
| `FORBIDDEN`                 | Key missing `suppressions:read` or `suppressions:write`  | Update the API Key                                                   |
| `NOT_FOUND`                 | ID or identity does not exist (or was already removed)   | Check workspace and value                                            |

***

## In message sending

| Code                   | What it means                           | What to do                                              |
| ---------------------- | --------------------------------------- | ------------------------------------------------------- |
| `RECIPIENT_SUPPRESSED` | Recipient is on the do-not-contact list | Query the entry; remove only if it makes business sense |

<Warning>
  Removing the suppression **re-enables sending immediately**. If the original issue (bounce, spam, opt-out) persists, the identity may return to the list automatically.
</Warning>

***

## Day-to-day situations

<AccordionGroup>
  <Accordion title="Customer sent STOP via SMS">
    The system creates a global **phone** suppression. SMS, WhatsApp, RCS, and voice are blocked. This is different from email marketing unsubscribe.
  </Accordion>

  <Accordion title="I imported CSV and some rows failed">
    In batch (`batch/add`), each row has an individual result. Invalid rows do not block valid ones. Fix only those that returned `invalid`.
  </Accordion>

  <Accordion title="I removed suppression but send still fails">
    Check that you removed the correct **normalized value**. Use `DELETE /v1/suppressions/by-identity` with the same `type` and value on the list.
  </Accordion>

  <Accordion title="Suppression vs tag vs topic">
    **Tag** organizes contacts. **Topic** is marketing consent. **Suppression** **blocks** sending. Email unsubscribe does not block SMS on its own.
  </Accordion>
</AccordionGroup>

***

## Next steps

* [Introduction](/en/suppressions-api/como-funciona/introducao): concepts and differences
* [Webhook events](/en/suppressions-api/como-funciona/eventos-do-webhooks): track in real time
* [API Key scopes](/en/suppressions-api/como-funciona/escopos-da-api-key): permissions