Erros - QX API

A API responde cada erro com o status HTTP e um corpo no formato da RFC 9457. O tipo do conteúdo é application/problem+json.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A chamada não trouxe uma chave de API válida. Envie a chave no cabeçalho Authorization, no formato Bearer <chave>.",
  "code": "unauthorized"
}

Os campos

Campo	O que traz
`type`	Sempre `about:blank`.
`title`	A frase do status HTTP, em inglês.
`status`	O status HTTP.
`detail`	A explicação do erro, em português. O texto pode mudar.
`code`	O código do erro, em inglês. O código não muda na v1.

Use o code para decidir o que o seu sistema faz. Mostre o detail a uma pessoa.

O erro de validação

A resposta 422 com o código validation_failed traz também a lista errors, com um item para cada campo com erro. Os outros códigos 422 têm uma causa só, que o code já nomeia, e não trazem a lista.

Campo	O que traz
`field`	O nome do campo.
`code`	O código do erro do campo, em inglês.
`message`	A explicação do erro do campo, em português.

Os códigos

Status	`code`	O que fazer
400	`invalid_parameter`	Corrija o parâmetro que o `detail` nomeia.
401	`unauthorized`	Confira a chave e o cabeçalho `Authorization`.
402	`subscription_blocked`	Regularize a assinatura no QX.
402	`trial_limit_reached`	Assine um plano no QX. A organização em teste chegou ao limite de documentos do teste.
403	`organization_archived`	Fale com o QX.
403	`plan_required`	Assine um plano pago no QX.
404	`not_found`	Confira o id. Um id de outra organização também recebe `404`.
409	`contact_exists`	Use o contato do campo `contact`. A organização já tem um contato com esse CPF ou CNPJ.
409	`idempotency_key_in_use`	Espere alguns segundos e repita a chamada com o mesmo `Idempotency-Key`. Veja Idempotência.
409	`document_has_content`	Envie o arquivo para um slot vazio. O documento já tem arquivo ou resposta.
409	`document_locked`	Confira o documento no QX. O documento está aprovado ou descartado, ou a coleta dele não recebe documentos.
413	`file_too_large`	Envie um arquivo menor. O limite é de 25 MB, e de 10 MB para o tipo sem campo de arquivo.
422	`validation_failed`	Corrija os campos da lista `errors`.
422	`contact_not_found`	Crie o contato com `POST /contacts` e repita a chamada.
422	`contact_archived`	Restaure o contato no QX, ou use outro contato.
422	`pack_unavailable`	Escolha um pacote ativo. O campo `active` de `GET /packs` mostra o pacote ativo.
422	`pack_not_for_contact`	Escolha um pacote que atende o tipo do contato. O campo `required_for` do pacote mostra o tipo.
422	`no_email`	Cadastre o e-mail do contato no QX, ou crie a coleta com `send_invitation` igual a `false`.
422	`contact_mismatch`	Envie o documento do contato da coleta, ou envie o documento sem `collection_id`.
422	`collection_not_accepting`	Escolha uma coleta aberta. A coleta está cancelada, arquivada ou com o parceiro, ou ainda não tem contato.
422	`document_type_inactive`	Escolha um tipo de documento ativo.
422	`document_type_without_file`	Escolha um tipo que recebe arquivo. O tipo é um formulário sem campo de arquivo.
422	`unsupported_file`	Envie o arquivo num formato que o tipo aceita. O tipo sem campo de arquivo aceita só PDF, JPEG e PNG.
422	`unknown_field`	Use a `key` de um campo que `GET /documents/{id}` mostra.
422	`idempotency_key_reused`	Use um valor novo de `Idempotency-Key` para a escrita nova. Veja Idempotência.
429	`rate_limited`	Espere os segundos do cabeçalho `Retry-After`.
429	`daily_limit_reached`	Espere os segundos do cabeçalho `Retry-After`. O limite volta à meia-noite, no fuso da organização.
429	`too_many_invalid_keys`	Corrija a chave e espere os segundos do cabeçalho `Retry-After`.
503	`storage_unavailable`	Repita a chamada em alguns segundos, com o mesmo `Idempotency-Key`. O QX não guardou o arquivo, e nenhum documento nasceu.