Troubleshooting

Each problem ends with the next step. If none of them solves it, send support the X-Request-Id of the call.

I got 401

The key did not arrive or is not valid. Check that:

• the header is Authorization: Bearer sdr_..., with the space after Bearer;
• the key was not revoked (dashboard, Integrações › Chaves de API (Integrations › API keys));
• the address has /api: https://api.sudrel.com.br/api/v1/....

I got 403

The key cannot do this. Two causes:

• Test key (sdr_test_) in a production-only operation: creating or changing a company, uploading a certificate, reading received documents. Use a sdr_live_ key.
• Key restricted to one company accessing another (acesso_negado) or managing webhooks (chave_restrita). Use a key without restriction.

I got 404 for an invoice or company that exists

It exists in the other environment. The test key sees only test invoices, and the production key only production ones. Check the key prefix.

I got 412

The company cannot issue: readiness has an item in bloqueio. The body carries the list in itens, with correcao in each one. Fix it and issue again. See Readiness.

I got 202

It is not an error. The invoice is transmitindo and Sudrel is still handling it. Wait for the webhook or query GET /v1/nfse/{id}. Do not issue again.

I got 409

Read codigo:

• referencia_duplicada: the invoice already exists. Query it by the nfse_id in the error.
• idempotencia_conflito: the same Idempotency-Key was used for another body. Generate one key per invoice.
• conflito: the same Idempotency-Key is still in progress. Wait a few seconds and repeat.
• referencia_ambigua: the reference exists in two companies. Repeat with ?empresa_id=.

See Idempotency.

I got 422

Read codigo, and then erros (each with campo, mensagem and correcao):

• validacao: the JSON has an error and nothing was created. Fix the items in erros.
• nfse_rejeitada: the Sistema Nacional NFS-e refused it. Read codigo_oficial and nfse.rejeicao.explicacao, fix it and issue a new invoice.
• tipo_invalido in /valor or in a tax rate: send it as text, "1500.00".

I got 429

More than 120 requests in the minute on this key. Wait for the next minute and repeat. If it happens all the time, replace repeated queries with webhooks and single invoices with batches.

The webhook did not arrive

1. Check that the webhook subscribes to the event type (GET /v1/webhooks/{id}) and that it is ativo.
2. Check the environment: a webhook created with the test key only receives test events.
3. See the attempts in GET /v1/webhooks/{id}/entregas: the HTTP status your server returned, or null when it did not even connect.
4. Your server must respond 2xx within 10 seconds. Redirects (3xx) are not followed and count as failures. Internal network addresses are refused.
5. Send a test: POST /v1/webhooks/{id}/teste.
6. Recover what you missed: POST /v1/webhooks/{id}/reenvio, or read GET /v1/eventos.

The webhook signature does not match

• Compute the HMAC over the raw body, the exact bytes, before any JSON.parse. Reserializing the JSON changes the bytes.
• The HMAC key is the secret as text, exactly as it came at creation.
• Use X-Sudrel-Signature-V2: the HMAC is of "<t>.<corpo>", not just the body.
• During a secret rotation two v1= values come: one match is enough.
• Check the server clock: the recommended tolerance is 5 minutes.

The invoice seems stuck

1. GET /v1/nfse/{id}: see status and the timeline in eventos.
2. transmitindo with aviso.codigo = "processamento_prolongado": Sudrel is still handling it. Do not issue again.
3. aguardando_confirmacao: it is waiting for you in POST /v1/nfse/{id}/confirmacao.
4. falha_transmissao: read falha.dps_enviada before anything else.
5. See the service situation on the status page.

I cannot find a call I made

Search for the X-Request-Id (or requisicao_id) in Integrações › Log da API (Integrations › API log), in the dashboard. The request and the response stay there for 30 days.