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

> ## Agent Instructions
> Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt.
> A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais.
> A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout.
> Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade.
> Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved.
> Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno.
> Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API.

# Erros e limites

> Trate falhas sem perder o contexto da operação nem repetir uma ação financeira por engano.

| HTTP | Significado | Ação |
| - | - | - |
| `400` / `422` | Dados inválidos | Corrija os campos indicados na resposta. |
| `401` | Autenticação inválida | Confira a chave e o header. |
| `403` | Acesso negado | Confira a empresa e as permissões. |
| `404` | Recurso não encontrado nesse contexto | Confira o identificador e a empresa. |
| `429` | Limite de requisições | Respeite `Retry-After`. |
| `5xx` | Falha no processamento | Registre horário, recurso e resposta; consulte o resultado antes de repetir uma escrita. |

## Formato do erro

Nas chamadas com chave de API, erros de validação, autenticação, permissão, recurso inexistente e limite trazem um código estável e o identificador da requisição:

```json theme={null}
{
  "detail": "Não encontrado.",
  "code": "not_found",
  "message": "Não encontrado.",
  "param": null,
  "requestId": "6f1c0b9e-2d4a-4c8e-9a51-0d3b7e2f8a10"
}
```

| Campo | Uso |
| - | - |
| `code` | Valor estável para decidir o tratamento (`not_found`, `permission_denied`, `not_authenticated`, `throttled`, `invalid`, `required`). |
| `message` | Mensagem em português para registro. Não compare textos. |
| `param` | Campo do primeiro erro de validação, ou `null`. |
| `requestId` | Igual ao header `X-Request-Id`. |

Erros de validação mantêm também a lista por campo, como `{"email": ["Informe um e-mail válido."]}`. Algumas operações ainda respondem só com `detail`; trate a ausência de `code` como erro genérico do status HTTP.

## Identificador da requisição

Toda resposta traz o header `X-Request-Id`. Ao falar com o suporte, envie esse valor: ele localiza a requisição nos registros da sinnu. Se a sua chamada enviar `X-Request-Id`, o mesmo valor volta na resposta.

## Limite por chave

A autenticação por chave aplica **100 requisições por minuto, por chave**. Distribua consultas ao longo do tempo e prefira webhooks para acompanhar mudanças de pagamento.

## Timeout não determina o resultado

Uma falha de rede pode ocorrer depois de o servidor receber a solicitação. Antes de reenviar uma criação ou um estorno, consulte o recurso e confira se a operação já foi aplicada.

O SDK atual não oferece retentativas automáticas nem uma opção de idempotência para criar links. Não acrescente headers de idempotência esperando um comportamento que o contrato não declara.

## O que registrar

Guarde método, caminho, status HTTP, horário, identificador do recurso e o `X-Request-Id` da resposta. Remova `Authorization`, segredos de webhook e dados pessoais dos registros enviados ao suporte.

No SDK, falhas HTTP geram [erros tipados](https://docs.sinnu.com.br/sdk/paginacao-e-erros.md). Falhas de rede podem manter o erro original de `fetch` e precisam de tratamento separado.


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