POST /vasp/customers/batch

Cadastra clientes finais do VASP em lote (até 1.000 por chamada)

Matrícula em lote de clientes finais (PF ou PJ). Cada item de customers tem o formato do corpo de POST /vasp/customers, inclusive document (CPF ou CNPJ em texto, que o servidor canoniza) e document_hash, que continua aceito. Se document e document_hash vierem juntos no mesmo item e divergirem, o item é recusado com DOCUMENT_HASH_MISMATCH. O servidor não guarda o documento em claro: com document, guarda só um índice cego e a cifra do valor; só com document_hash, não tem o documento para cifrar e não consegue exibi-lo.

Cada item é processado por conta própria: um item recusado não impede os outros. O resultado de cada item é CREATED (titular novo), UPDATED (o external_id já existia na empresa, e o titular é atualizado pelo próprio external_id; campo ausente no item não apaga o valor anterior) ou REJECTED, com o motivo de validação. type e client_id do titular não mudam por esta via: item que traga type diferente do titular existente, ou client_id diferente do vínculo existente (ou um client_id para titular que não tinha vínculo), volta REJECTED com invalid_customer. O resultado não revela se o documento já existe sob outro external_id: o mesmo documento sob external_id diferentes é aceito, sem aviso e sem recusa.

A resposta é 207 sempre que o lote foi lido e autorizado, mesmo que todos os itens tenham sido recusados. O resultado de cada item vem em results, na ordem do envio, e os totais em summary.

Limites. Além do limite da chave de API, esta operação tem limites próprios: por lote (de 1 a 1.000 titulares, e o corpo inteiro respeita o teto de 1 MiB da API; se o lote não couber, divida-o), por ator (a chave de API que envia o lote) e por empresa, e um orçamento de itens por janela de tempo, também por empresa. Ao esgotar qualquer um deles, a resposta é 429, com Retry-After, e nada é processado.

O mesmo external_id mais de uma vez no lote recusa o lote inteiro (422 DUPLICATE_EXTERNAL_ID), sem gravar nada. Corpo ilegível, campo desconhecido na raiz do corpo e customers fora de 1 a 1.000 itens também respondem 422, com INVALID_BATCH. Idempotency-Key é obrigatória: a repetição com a mesma chave e o mesmo corpo devolve o resultado original, sem gravar de novo (idempotent_replay: true), e a mesma chave com corpo diferente responde 409.

Matrícula básica de KYT, autenticada por API key com o escopo vasp:customers:write. Funciona com o cruzamento desligado e não exige o adicional de cruzamento de dados do titular.

Item	Valor
Método	POST
Caminho	/vasp/customers/batch
URL	https://crypto-api.sentinexrisk.com/api/v1/vasp/customers/batch
Grupo	VASP - Clientes
operationId	createVASPCustomersBatch
Versão do contrato	8.5.1

Autenticação

Chave de API do tenant no header X-API-Key (esquema ApiKeyAuth). A chave identifica o tenant e carrega os escopos; não existe header de tenant. Detalhes em Autenticação.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
Idempotency-Key	header	string	sim	Obrigatória. Mesma chave + corpo igual = replay; corpo diferente = 409. O prefixo snx-derived: é RESERVADO ao servidor em TODAS as rotas desta API: uma Idempotency-Key que comece com ele é recusada com 400. De 1 a 255 caracteres. Exemplo: lote-clientes-01.

Corpo da requisição

Corpo obrigatório.

Tipo de mídia application/json.

Schema VASPCustomerBatchRequest, do tipo objeto.

Não aceita propriedades além das listadas.

Campo	Tipo	Obrigatório	Descrição
customers	lista de objeto (VASPCustomerCreateRequest)	sim	De 1 a 1.000 clientes finais por chamada. Cada item tem o formato do corpo de POST /vasp/customers. Ao menos 1 item(ns). Até 1000 itens.
customers[].client_id	string (uuid)	não	Opcional. Id do cliente Sentinex que é o mesmo titular: o id devolvido por POST /clients, o mesmo que a análise KYT recebe como client_id. É gravado uma vez e não tem rota de alteração. Sem ele, o KYC externo deste cliente (convite e push) responde 403 client_link_required. UUID zero ou texto que não é UUID responde 400 invalid_client_id; cliente que não é desta empresa responde 422 client_not_found.
customers[].external_id	string	sim	Id do cliente no seu sistema. Padrão: letras, números, ponto, underscore, dois-pontos, hífen. Até 128 caracteres.
customers[].type	string	sim	Valores: PF, PJ.
customers[].document_hash	string	não	SHA-256 hex do CPF/CNPJ, com prefixo sha256 opcional. Continua aceito. Envie document_hash ou document; um dos dois é obrigatório. Só com document_hash, o servidor não tem o documento para cifrar e não consegue exibi-lo em tela nem em laudo. Se vier junto de document e divergir, a resposta é 422 DOCUMENT_HASH_MISMATCH. Neste campo, nunca envie o documento em claro: para isso existe document.
customers[].document	string	não	Opcional. CPF ou CNPJ do titular em texto, com ou sem pontuação (o CNPJ pode ser numérico ou alfanumérico). O servidor canoniza o valor (CPF só com os 11 dígitos; CNPJ em maiúsculas e sem pontuação) e confere os dígitos verificadores. O servidor não guarda o documento em claro: guarda só um índice cego, calculado com uma chave da empresa mantida fora do banco, que serve para buscar e comparar, e a cifra do valor, para exibição a quem tem permissão. Não é SHA-256 sem sal. document tem precedência no cálculo do índice. document_hash continua aceito; envie um dos dois. Se vierem os dois e divergirem, a resposta é 422 DOCUMENT_HASH_MISMATCH. O documento nunca é devolvido em resposta. Os exemplos deste contrato usam documentos fictícios. De 11 a 32 caracteres. Só de escrita: a API nunca devolve este campo. Exemplo: 123.456.789-01.
customers[].document_country	string	não	ISO-3166 alpha-2 (default BR).
customers[].legal_name_hash	string	não	SHA-256 hex do nome/razão social (opcional).
customers[].trade_name	string	não	Até 255 caracteres.
customers[].incorporation_date	string (date)	não	YYYY-MM-DD (PJ).
customers[].country	string	não	ISO-3166 alpha-2 (default BR).
customers[].state	string	não	Até 255 caracteres.
customers[].kyc_tier	string	não	Default STANDARD. Valores: SIMPLIFIED, STANDARD, ENHANCED.
customers[].kyc_completed_at	string (date-time)	não
customers[].external_kyc_provider	string	não	Até 255 caracteres.
customers[].external_kyc_reference_url	string	não	URL https absoluta (máx. 2048 chars).
customers[].risk_classification	string	não	Default MEDIUM. Valores: LOW, MEDIUM, HIGH, CRITICAL.
customers[].tags	lista de string	não	Até 50 itens.
customers[].attributes	objeto	não	JSON livre (máx. 16 KB). Chaves/valores com identificadores pessoais em claro (cpf, cnpj, email, phone, nomes) são rejeitados com 400.
customers[].consent_data_share	boolean	não
customers[].consent_data_share_at	string (date-time)	não
customers[].source	string	não	Default api.
customers[].source_event_id	string	não	Até 255 caracteres.

Exemplo de corpo, publicado no contrato:

{
  "customers": [
    {
      "external_id": "cliente-0001",
      "type": "PF",
      "document": "123.456.789-01"
    },
    {
      "external_id": "cliente-0002",
      "type": "PJ",
      "document": "11.222.333/0001-82",
      "trade_name": "Empresa Exemplo"
    }
  ]
}

Exemplo de chamada

curl -X POST "https://crypto-api.sentinexrisk.com/api/v1/vasp/customers/batch" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d @corpo.json

O arquivo corpo.json segue o schema do corpo acima.

Respostas de sucesso

Status	Descrição
207	Lote lido e autorizado. O status vale para o lote; o resultado de cada item, criado, atualizado ou recusado, está em results.

207

Lote lido e autorizado. O status vale para o lote; o resultado de cada item, criado, atualizado ou recusado, está em results.

Tipo de mídia application/json.

Schema VASPCustomerBatchResponse, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Verdadeiro quando o lote foi lido e processado, mesmo que itens tenham sido recusados. Leia results.
idempotent_replay	boolean	sim	Sempre presente. Verdadeiro quando é o resultado original, devolvido na repetição com a mesma Idempotency-Key e o mesmo corpo; falso na primeira execução.
summary	objeto	sim
summary.total	integer	sim	Mínimo: 0.
summary.created	integer	sim	Mínimo: 0.
summary.updated	integer	sim	Mínimo: 0.
summary.rejected	integer	sim	Mínimo: 0.
results	lista de objeto (VASPCustomerBatchItemResult)	sim	Um resultado por item, na ordem do envio.
results[].index	integer	sim	Posição do item em customers, contada a partir de 0. Mínimo: 0.
results[].external_id	string	não	O external_id normalizado do titular. Vem só quando o status é CREATED ou UPDATED; item REJECTED não o repete (use index).
results[].status	string	sim	CREATED quando o titular é novo e foi gravado. UPDATED quando o external_id já existia na empresa e o titular foi atualizado por ele. REJECTED quando o item foi recusado por validação e nada foi gravado para ele. Valores: CREATED, UPDATED, REJECTED.
results[].data	objeto (VASPCustomer)	não	Projeção retornada pelos endpoints /vasp/customers.
results[].data.id	string	não	Id do cliente, no formato UUID.
results[].data.tenant_id	string (uuid)	não
results[].data.client_id	string ou null	não	Vínculo com o cliente Sentinex, no formato UUID; nulo quando a matrícula não o informou.
results[].data.external_id	string	não
results[].data.type	string	não	Valores: PF, PJ.
results[].data.document_country	string	não
results[].data.trade_name	string	não
results[].data.incorporation_date	string (date-time) ou null	não
results[].data.country	string	não
results[].data.state	string	não
results[].data.kyc_tier	string	não	Valores: SIMPLIFIED, STANDARD, ENHANCED.
results[].data.kyc_completed_at	string (date-time) ou null	não
results[].data.external_kyc_provider	string	não
results[].data.external_kyc_reference_url	string	não
results[].data.risk_classification	string	não	Valores: LOW, MEDIUM, HIGH, CRITICAL.
results[].data.tags	lista de string	não
results[].data.attributes	objeto	não
results[].data.consent_data_share	boolean	não
results[].data.consent_data_share_at	string (date-time) ou null	não
results[].data.screening_status	string	não
results[].data.receita_status	string	não
results[].data.source	string	não
results[].data.source_event_id	string	não
results[].data.created_at	string (date-time)	não
results[].data.updated_at	string (date-time)	não
results[].error	objeto	não
results[].error.code	string	sim	Código estável de validação do item: invalid_customer, invalid_client_id, client_not_found ou DOCUMENT_HASH_MISMATCH. Trate código desconhecido como erro genérico: a lista pode crescer. Nenhum código diz que o documento já existe sob outro external_id.
results[].error.message	string	sim	Texto fixo, Item recusado por validação.; não detalha o campo.

Exemplo publicado no contrato:

{
  "success": true,
  "idempotent_replay": false,
  "summary": {
    "total": 3,
    "created": 1,
    "updated": 1,
    "rejected": 1
  },
  "results": [
    {
      "index": 0,
      "external_id": "cliente-0001",
      "status": "CREATED",
      "data": {
        "external_id": "cliente-0001",
        "type": "PF"
      }
    },
    {
      "index": 1,
      "external_id": "cliente-0002",
      "status": "UPDATED",
      "data": {
        "external_id": "cliente-0002",
        "type": "PJ"
      }
    },
    {
      "index": 2,
      "status": "REJECTED",
      "error": {
        "code": "invalid_customer",
        "message": "Item recusado por validação."
      }
    }
  ]
}

Códigos de erro declarados

Estes são os códigos que o contrato declara para esta operação. Os limites que valem para toda a API, antes da autenticação, estão em Limites de requisição.

Status	Descrição
400	Idempotency-Key ausente ou inválida (invalid_idempotency_key): vazia depois do trim, com mais de 255 bytes, com caractere de controle ou com o prefixo reservado snx-derived:. Corpo ilegível e customers fora de 1 a 1.000 itens não caem aqui (são 422 INVALID_BATCH), e item inválido volta recusado em results.
401	A chave de API não autenticou a requisição, e nenhuma camada adiante rodou. error.code é missing_api_key (nenhuma chave em X-API-Key nem em Authorization: Bearer snxc_...) ou invalid_api_key (chave desconhecida, revogada ou expirada). Quando a plataforma não consegue verificar a chave, a resposta é 503 com api_key_verification_unavailable, e não 401: repita com backoff.
402	Conta sem direito comercial (TRIAL_EXPIRED): trial vencido, trial sem data ou empresa sem contrato. A requisição NÃO foi processada; uma triagem recusada assim é transação não triada, nunca aprovada.
403	Acesso recusado antes da operação, nesta ordem de camadas: o escudo de borda recusa travessia de diretório na URL (ErroTexto); a chave é recusada pelo IP de origem (api_key_ip_not_allowed); o ambiente da chave não é aceito por esta implantação (api_key_environment_required ou api_key_environment_not_allowed); a conta não pode usar a API (TenantAccessRefusalResponse: empresa_SUSPENDED, empresa_NOT_OPERATIONAL, API_ACCESS_DISABLED ou empresa_ACCESS_DENIED); a chave não tem o escopo da rota (insufficient_scope, com o escopo na mensagem). Não repita sem corrigir a causa.
404	Com chave válida, o caminho ou o método não corresponde a operação servida por esta implantação (error.code route_not_found). Confira método, caminho e o prefixo /api/v1.
409	Idempotency-Key reusada com corpo diferente (KYT_IDEMPOTENCY_CONFLICT)
413	Corpo acima de 1 MiB. O escudo de borda recusa antes da autenticação, com BODY_TOO_LARGE; a própria operação repete o teto com BATCH_PAYLOAD_TOO_LARGE. Nada foi gravado. Lote com mais de 1.000 titulares dentro do teto de tamanho é 422 INVALID_BATCH.
422	Lote recusado por inteiro, sem gravar nada: INVALID_BATCH (corpo ilegível, campo desconhecido na raiz, ou customers fora de 1 a 1.000 itens) ou DUPLICATE_EXTERNAL_ID (o lote repete um external_id).
429	Limite de requisições atingido; nada foi processado. Valem as formas de ErroLimiteDeRequisicoes (limite da chave, limite global e escudo de borda) e os limites próprios do lote: por ator (BATCH_RATE_LIMIT_ACTOR) e por empresa (BATCH_RATE_LIMIT_TENANT), ambos por hora e com Retry-After: 3600 (ErroLimiteDoLote), e o orçamento de itens da empresa (BATCH_ITEM_BUDGET_EXCEEDED, ErrorResponseCoded, também com Retry-After: 3600). Espere o Retry-After antes de repetir.
500	Falha inesperada. A mensagem é genérica de propósito; guarde o X-Request-ID da resposta para o suporte e repita com espera.
503	Matrícula em lote indisponível: chaves da empresa, proteção do lote, recibo do lote ou banco (ErroTexto); nenhum item do lote ficou gravado. Sem contador de limite de lote, a rota recusa em vez de deixar passar (BATCH_RATE_LIMIT_UNAVAILABLE). As camadas anteriores à operação também respondem 503, nada processado: limitador por IP ou da empresa sem contagem (ErroTexto), estado da conta (empresa_ACCESS_STATE_UNAVAILABLE), limitador da chave (rate_limit_unavailable) e verificação da chave (api_key_verification_unavailable).

400

Idempotency-Key ausente ou inválida (invalid_idempotency_key): vazia depois do trim, com mais de 255 bytes, com caractere de controle ou com o prefixo reservado snx-derived:. Corpo ilegível e customers fora de 1 a 1.000 itens não caem aqui (são 422 INVALID_BATCH), e item inválido volta recusado em results.

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

401

A chave de API não autenticou a requisição, e nenhuma camada adiante rodou. error.code é missing_api_key (nenhuma chave em X-API-Key nem em Authorization: Bearer snxc_...) ou invalid_api_key (chave desconhecida, revogada ou expirada). Quando a plataforma não consegue verificar a chave, a resposta é 503 com api_key_verification_unavailable, e não 401: repita com backoff.

Resposta compartilhada ErroChaveNaoAutenticada do contrato.

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

402

Conta sem direito comercial (TRIAL_EXPIRED): trial vencido, trial sem data ou empresa sem contrato. A requisição NÃO foi processada; uma triagem recusada assim é transação não triada, nunca aprovada.

Resposta compartilhada TenantAccessPaymentRequired do contrato.

Tipo de mídia application/json.

Schema TenantAccessRefusalResponse, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code	string	sim	Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details	objeto	não
details.reason	string	não	Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at	string (date-time)	não	Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state	string	não	Presente em empresa_NOT_OPERATIONAL.

403

Acesso recusado antes da operação, nesta ordem de camadas: o escudo de borda recusa travessia de diretório na URL (ErroTexto); a chave é recusada pelo IP de origem (api_key_ip_not_allowed); o ambiente da chave não é aceito por esta implantação (api_key_environment_required ou api_key_environment_not_allowed); a conta não pode usar a API (TenantAccessRefusalResponse: empresa_SUSPENDED, empresa_NOT_OPERATIONAL, API_ACCESS_DISABLED ou empresa_ACCESS_DENIED); a chave não tem o escopo da rota (insufficient_scope, com o escopo na mensagem). Não repita sem corrigir a causa.

Resposta compartilhada ErroAcessoNegado do contrato.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, TenantAccessRefusalResponse, ErroTexto.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

Alternativa do corpo: TenantAccessRefusalResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code	string	sim	Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details	objeto	não
details.reason	string	não	Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at	string (date-time)	não	Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state	string	não	Presente em empresa_NOT_OPERATIONAL.

Alternativa do corpo: ErroTexto

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Carteira não encontrada..

404

Com chave válida, o caminho ou o método não corresponde a operação servida por esta implantação (error.code route_not_found). Confira método, caminho e o prefixo /api/v1.

Resposta compartilhada ErroRotaNaoEncontrada do contrato.

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

409

Idempotency-Key reusada com corpo diferente (KYT_IDEMPOTENCY_CONFLICT)

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

413

Corpo acima de 1 MiB. O escudo de borda recusa antes da autenticação, com BODY_TOO_LARGE; a própria operação repete o teto com BATCH_PAYLOAD_TOO_LARGE. Nada foi gravado. Lote com mais de 1.000 titulares dentro do teto de tamanho é 422 INVALID_BATCH.

Tipo de mídia application/json.

Tipo um de: ErroTextoComCodigo, ErrorResponseCoded.

Alternativa do corpo: ErroTextoComCodigo

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim
code	string	sim	Exemplo: BODY_TOO_LARGE.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

422

Lote recusado por inteiro, sem gravar nada: INVALID_BATCH (corpo ilegível, campo desconhecido na raiz, ou customers fora de 1 a 1.000 itens) ou DUPLICATE_EXTERNAL_ID (o lote repete um external_id).

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

429

Limite de requisições atingido; nada foi processado. Valem as formas de ErroLimiteDeRequisicoes (limite da chave, limite global e escudo de borda) e os limites próprios do lote: por ator (BATCH_RATE_LIMIT_ACTOR) e por empresa (BATCH_RATE_LIMIT_TENANT), ambos por hora e com Retry-After: 3600 (ErroLimiteDoLote), e o orçamento de itens da empresa (BATCH_ITEM_BUDGET_EXCEEDED, ErrorResponseCoded, também com Retry-After: 3600). Espere o Retry-After antes de repetir.

Header	Tipo	Descrição
Retry-After	integer	Segundos a esperar antes de repetir. Vem nos 429 dos limitadores (salvo a rajada do escudo) e no 503 de transação que conflitou (1 segundo).
X-RateLimit-Limit	integer	Teto da janela do limitador que respondeu, quando ele informa.
X-RateLimit-Remaining	integer	Requisições restantes na janela, quando o limitador informa.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, ErroLimiteDoLote, ErroLimite.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

Alternativa do corpo: ErroLimiteDoLote

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim
code	string	sim	Valores: BATCH_RATE_LIMIT_ACTOR, BATCH_RATE_LIMIT_TENANT.
retry	string	sim	Orientação em texto de quando repetir. Exemplo: wait until next hour.
window	string	sim	Exemplo: 1 hour.
limit	integer	sim	Teto de lotes por hora do escopo que recusou. Mínimo: 1.

Alternativa do corpo: ErroLimite

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Too many requests. Please try again later..
retry_after	integer	não	Mínimo: 1. Exemplo: 3600.
code	string	não	Exemplo: RATE_LIMIT_HARD.
reference	string	não	Identificador curto do bloqueio, para citar ao suporte.
detail	string	não

500

Falha inesperada. A mensagem é genérica de propósito; guarde o X-Request-ID da resposta para o suporte e repita com espera.

Resposta compartilhada ErroInterno do contrato.

Tipo de mídia application/json.

Schema ErroTexto, do tipo objeto.

Envelope de erro com a mensagem em texto no campo error, sem código. É o formato dos handlers de cadastro, carteira, webhooks, ledger e leituras regulatórias, da recuperação de falha inesperada (500), da indisponibilidade das camadas de borda (503) e da recusa do escudo de borda por padrão de ataque (403). Ramifique pelo status HTTP; a mensagem é texto livre e pode mudar.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Carteira não encontrada..

503

Matrícula em lote indisponível: chaves da empresa, proteção do lote, recibo do lote ou banco (ErroTexto); nenhum item do lote ficou gravado. Sem contador de limite de lote, a rota recusa em vez de deixar passar (BATCH_RATE_LIMIT_UNAVAILABLE). As camadas anteriores à operação também respondem 503, nada processado: limitador por IP ou da empresa sem contagem (ErroTexto), estado da conta (empresa_ACCESS_STATE_UNAVAILABLE), limitador da chave (rate_limit_unavailable) e verificação da chave (api_key_verification_unavailable).

Header	Tipo	Descrição
Retry-After	integer	Segundos a esperar antes de repetir. Vem nos 429 dos limitadores (salvo a rajada do escudo) e no 503 de transação que conflitou (1 segundo).

Tipo de mídia application/json.

Tipo um de: ErroTexto, TenantAccessRefusalResponse, ErrorResponseCoded, ErroTextoComCodigo.

Alternativa do corpo: ErroTexto

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Carteira não encontrada..

Alternativa do corpo: TenantAccessRefusalResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code	string	sim	Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details	objeto	não
details.reason	string	não	Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at	string (date-time)	não	Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state	string	não	Presente em empresa_NOT_OPERATIONAL.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

Alternativa do corpo: ErroTextoComCodigo

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim
code	string	sim	Exemplo: BODY_TOO_LARGE.