Erros

Formato do erro

Os erros tratados pela API usam application/problem+json.

{
  "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 e protocol_id em 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.

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.
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`. 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`	Corrija os campos de `field_errors`.
`idempotency_key_required`	Envie o cabeçalho `Idempotency-Key`.

401 Não autenticado

Código	Próxima ação
`missing_or_invalid_authorization`	Confira o cabeçalho `Authorization`.
`invalid_api_key`	Confira a chave de API.
`api_key_revoked`	Crie uma chave de API.

402 Saldo insuficiente

Código	Próxima ação
`insufficient_credits`	Adicione saldo.

403 Sem permissão

Código	Próxima ação
`product_not_enabled`	Escolha um certificado disponível para o parceiro.
`partner_not_approved`	Fale com o suporte da ZapSign.
`forbidden`	Envie a chamada pelo seu servidor.

404 Não encontrado

Código	Próxima ação
`not_found`	Confira o caminho da chamada e o `protocol_id`.

409 Conflito

Código	Próxima ação
`external_id_taken`	Consulte o protocolo informado em `protocol_id`.
`idempotency_conflict`	Reenvie o corpo original ou use outra chave para uma nova ação.
`action_not_allowed`	Confira o status do protocolo e as ações permitidas.
`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`	Use uma combinação retornada por `GET /protocol-products`.
`video_not_eligible`	Consulte a ação indicada para `reason`.
`official_data_unavailable`	Tente novamente mais tarde.
`holder_email_in_use`	Use outro e-mail, do próprio cliente.

429 Limite de chamadas

Código	Próxima ação
`rate_limited`	Aguarde os segundos indicados em `Retry-After`.

500 Erro do nosso lado

Código	Próxima ação
`internal_error`	Tente novamente em instantes.

503 Serviço indisponível

Código	Próxima ação
`service_unavailable`	Aguarde os segundos indicados em `Retry-After`.

Referência da API

Protocolos

Verificação

Agendamento

Saldo e catálogo

Formato do erro

Como reagir

Quando tentar de novo

Códigos

400 Requisição inválida

401 Não autenticado

402 Saldo insuficiente

403 Sem permissão

404 Não encontrado

409 Conflito

422 Não foi possível processar

429 Limite de chamadas

500 Erro do nosso lado

503 Serviço indisponível

​Formato do erro

​Como reagir

​Quando tentar de novo

​Códigos

​400 Requisição inválida

​401 Não autenticado

​402 Saldo insuficiente

​403 Sem permissão

​404 Não encontrado

​409 Conflito

​422 Não foi possível processar

​429 Limite de chamadas

​500 Erro do nosso lado

​503 Serviço indisponível

Formato do erro

Como reagir

Quando tentar de novo

Códigos

400 Requisição inválida

401 Não autenticado

402 Saldo insuficiente

403 Sem permissão

404 Não encontrado

409 Conflito

422 Não foi possível processar

429 Limite de chamadas

500 Erro do nosso lado

503 Serviço indisponível