> ## Documentation Index > Fetch the complete documentation index at: https://docs.certificados.zapsign.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Erros > Formato dos erros e o que fazer em cada código. ## Formato do erro Os erros tratados pela API usam `application/problem+json`. ```json theme={"system"} { "code": "validation_error", "message": "Erro de validação no corpo da requisição.", "retryable": false, "field_errors": [ { "field": "time", "message": "Use um horário no formato HH:MM." } ], "status": 400, "type": "https://docs.certificados.zapsign.com.br/erros/validation_error", "request_id": "01K7Q4A1B2C3D4E5F6G7H8J9KM" } ``` | Campo | O que é | | - | - | | `code` | O código do erro. Use-o para decidir o que fazer. | | `message` | Uma explicação em português, para consultar nos registros da integração. Não use como condição no código. | | `retryable` | Indica se a API recomenda repetir a chamada. Siga a orientação do código do erro. | | `field_errors` | Campos que precisam de correção e o motivo, quando informados. | | `status` | O status HTTP, igual ao da resposta. | | `type` | O endereço da página do código, com o que aconteceu e o que fazer. | | `request_id` | O identificador da chamada, igual ao cabeçalho `X-Request-Id`. Informe-o ao suporte. | Alguns erros trazem um campo extra: `reason` em [`video_not_eligible`](https://docs.certificados.zapsign.com.br/erros/video_not_eligible) e `protocol_id` em [`external_id_taken`](https://docs.certificados.zapsign.com.br/erros/external_id_taken). Não confunda os dois `reason`. O `reason` deste erro HTTP só existe em `video_not_eligible`, na resposta de `POST /protocols`. Já o `error.reason` do protocolo aparece em `GET /protocols/{protocol_id}`, dentro de `error`, quando a criação falhou depois de aceita: hoje o único valor é `holder_email_in_use`. Veja os [códigos de `error`](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo#códigos-de-error). ## Como reagir * Siga a próxima ação indicada para o `code` da resposta. * Ao repetir uma ação que exige `Idempotency-Key`, envie a mesma chave. Veja [Idempotência](https://docs.certificados.zapsign.com.br/idempotencia.md). * Nos erros `4xx` de `POST /protocols`, nenhum protocolo é criado e o saldo não é descontado. * Depois de um erro `5xx` ou de um tempo limite em `POST /protocols`, reenvie com a mesma chave e o mesmo corpo. Se o protocolo já foi criado, a API devolve esse protocolo com `Idempotent-Replayed: true` e não cria outro. * Trate também respostas sem corpo `problem+json` (como redirecionamentos e alguns `400`, `403` e `431` de infraestrutura): decida pelo status HTTP. ## Quando tentar de novo | Resposta | Tente de novo? | O que fazer | | - | - | - | | `429 rate_limited` | Sim | Aguarde os segundos de `Retry-After`. Mantenha a chave e o corpo. | | `503 service_unavailable` | Sim | Aguarde os segundos de `Retry-After`. Mantenha a chave e o corpo. | | `500 internal_error` | Sim | Tente novamente em instantes, com a mesma chave. A resposta não traz `Retry-After`. | | `409 operation_in_progress` | Sim, depois de consultar | Aguarde alguns segundos e consulte o protocolo. Reenvie com a mesma chave e os mesmos dados. A resposta não traz `Retry-After`. | | `422 official_data_unavailable` | Mais tarde | Nenhum protocolo foi criado. A resposta não traz `Retry-After`. | | `422 holder_email_in_use` | Com outro e-mail | Nenhum protocolo foi criado. Troque o e-mail e reenvie com a mesma chave e o mesmo `external_id`. O mesmo e-mail só volta a ser aceito se for liberado; não o repita esperando essa liberação. | | Outros `4xx` com `retryable: false` | Só depois de corrigir | Siga a próxima ação do `code`. Não repita a mesma chamada. | | `200` com `error` no protocolo | Depende de `error.code` | Veja os [códigos de `error`](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo#códigos-de-error). Para tentar de novo, use uma nova chave. | | Tempo limite ou erro de rede | Sim | Reenvie com a mesma chave e o mesmo corpo. | ## Códigos ### 400 Requisição inválida | Código | Próxima ação | | - | - | | [`validation_error`](https://docs.certificados.zapsign.com.br/erros/validation_error) | Corrija os campos de `field_errors`. | | [`idempotency_key_required`](https://docs.certificados.zapsign.com.br/erros/idempotency_key_required) | Envie o cabeçalho `Idempotency-Key`. | ### 401 Não autenticado | Código | Próxima ação | | - | - | | [`missing_or_invalid_authorization`](https://docs.certificados.zapsign.com.br/erros/missing_or_invalid_authorization) | Confira o cabeçalho `Authorization`. | | [`invalid_api_key`](https://docs.certificados.zapsign.com.br/erros/invalid_api_key) | Confira a chave de API. | | [`api_key_revoked`](https://docs.certificados.zapsign.com.br/erros/api_key_revoked) | Crie uma chave de API. | ### 402 Saldo insuficiente | Código | Próxima ação | | - | - | | [`insufficient_credits`](https://docs.certificados.zapsign.com.br/erros/insufficient_credits) | Adicione saldo. | ### 403 Sem permissão | Código | Próxima ação | | - | - | | [`product_not_enabled`](https://docs.certificados.zapsign.com.br/erros/product_not_enabled) | Escolha um certificado disponível para o parceiro. | | [`partner_not_approved`](https://docs.certificados.zapsign.com.br/erros/partner_not_approved) | Fale com o suporte da ZapSign. | | [`forbidden`](https://docs.certificados.zapsign.com.br/erros/forbidden) | Envie a chamada pelo seu servidor. | ### 404 Não encontrado | Código | Próxima ação | | - | - | | [`not_found`](https://docs.certificados.zapsign.com.br/erros/not_found) | Confira o caminho da chamada e o `protocol_id`. | ### 409 Conflito | Código | Próxima ação | | - | - | | [`external_id_taken`](https://docs.certificados.zapsign.com.br/erros/external_id_taken) | Consulte o protocolo informado em `protocol_id`. | | [`idempotency_conflict`](https://docs.certificados.zapsign.com.br/erros/idempotency_conflict) | Reenvie o corpo original ou use outra chave para uma nova ação. | | [`action_not_allowed`](https://docs.certificados.zapsign.com.br/erros/action_not_allowed) | Confira o status do protocolo e as ações permitidas. | | [`operation_in_progress`](https://docs.certificados.zapsign.com.br/erros/operation_in_progress) | Aguarde e consulte o protocolo antes de tentar novamente. | ### 422 Não foi possível processar | Código | Próxima ação | | - | - | | [`certificate_combination_not_supported`](https://docs.certificados.zapsign.com.br/erros/certificate_combination_not_supported) | Use uma combinação retornada por `GET /protocol-products`. | | [`video_not_eligible`](https://docs.certificados.zapsign.com.br/erros/video_not_eligible) | Consulte a ação indicada para `reason`. | | [`official_data_unavailable`](https://docs.certificados.zapsign.com.br/erros/official_data_unavailable) | Tente novamente mais tarde. | | [`holder_email_in_use`](https://docs.certificados.zapsign.com.br/erros/holder_email_in_use) | Use outro e-mail, do próprio cliente. | ### 429 Limite de chamadas | Código | Próxima ação | | - | - | | [`rate_limited`](https://docs.certificados.zapsign.com.br/erros/rate_limited) | Aguarde os segundos indicados em `Retry-After`. | ### 500 Erro do nosso lado | Código | Próxima ação | | - | - | | [`internal_error`](https://docs.certificados.zapsign.com.br/erros/internal_error) | Tente novamente em instantes. | ### 503 Serviço indisponível | Código | Próxima ação | | - | - | | [`service_unavailable`](https://docs.certificados.zapsign.com.br/erros/service_unavailable) | Aguarde os segundos indicados em `Retry-After`. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.