Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

Referência dos códigos HTTP usados por toda a API da Rapid.

CódigoSignificado
200Sucesso com corpo
201Recurso criado
204Sucesso sem corpo (ex.: Remover merchant)
CódigoSignificado
400Corpo que não é JSON válido (INVALID_JSON)
401Credenciais ausentes ou inválidas
403Empresa bloqueada, cadastro da empresa ainda não aprovado (KYB_NOT_APPROVED), ou produto necessário não ativo (PRODUCT_NOT_ACTIVE)
404Recurso não encontrado
405Operação não permitida (TRANSACTION_DELETE_NOT_ALLOWED)
409Conflito (duplicata, atualização de recurso imutável)
413Corpo acima do tamanho máximo (PAYLOAD_TOO_LARGE)
422Erro de validação
429Muitas requisições (rate limit)
CódigoSignificado
500Erro interno (INTERNAL_ERROR), retentativa recomendada
503Indisponibilidade temporária (SERVICE_UNAVAILABLE, CAPTURE_TEMPORARILY_UNAVAILABLE), com Retry-After

Toda resposta de erro tem a estrutura:

{
"error": {
"code": "CODIGO_SEMANTICO",
"message": "Descrição legível do erro"
}
}

O message vem em inglês e é para quem lê o log: o texto pode mudar. Para decidir o que fazer no seu código, use o code. Os endpoints mantidos do sistema anterior respondem como antes.

Alguns erros trazem também params e details, só quando existem:

{
"error": {
"code": "FIELD_TOO_LONG",
"message": "name must be at most 255 characters",
"params": { "field": "name", "max": 255 }
}
}
  • params: os dados do erro, como o campo (field), o limite (max) ou o id do recurso em conflito (merchant_id, enrollment_id).
  • details: no lote tudo ou nada recusado (ENROLLMENT_BATCH_INVALID), a lista errors com index, code, message e params de cada item recusado.

Quem lê só code e message não precisa mudar nada.

CódigoHTTPUso
INVALID_JSON400O corpo não é um JSON válido
UNAUTHORIZED401Credenciais ausentes ou inválidas
COMPANY_BLOCKED403Empresa bloqueada
PRODUCT_NOT_ACTIVE403Criação de transação sem Prevenção nem Disputa ativa (ver Quem envia transações), ou pedido de enrollment de um produto que a sua empresa não tem ativo (params.product)
VALIDATION_ERROR422Um ou mais campos inválidos
NOT_FOUND404O endereço não existe na API (caminho com erro de digitação, barra sobrando no fim)
TRANSACTION_NOT_FOUND404Transação inexistente
TRANSACTION_DUPLICATE409external_source + external_id já cadastrado
TRANSACTION_IMMUTABLE409Transação já utilizada, não pode ser atualizada
TRANSACTION_DELETE_NOT_ALLOWED405Transações não podem ser apagadas (ver Deletar transação)
MERCHANT_NOT_FOUND404Merchant inexistente
ALERT_NOT_FOUND404Alerta inexistente
ALERT_INVALID_STATUS422Status inválido, ou transição não permitida (prazo, expiração ou status já definitivo)
PAYLOAD_TOO_LARGE413Corpo acima do limite: 1 MB por requisição, 5 MB no envio em lote e no lote de merchants, 2 MB no lote de enrollments
RATE_LIMIT_EXCEEDED429Limite de requisições excedido (ver abaixo)
ORIGIN_NOT_ALLOWED403Evento de captura vindo de um site que não está entre os sites em que o token vale (ver Em qual site o token vale)
TOO_MANY_PENDING_EVENTS429Eventos de captura demais esperando a transação aparecer (ver Limite de chamadas)
CAPTURE_TEMPORARILY_UNAVAILABLE503Captura temporariamente indisponível. Reenvie o evento depois do Retry-After, com o mesmo event_id
SERVICE_UNAVAILABLE503Indisponibilidade temporária em merchants, enrollments e uso. Repetir é seguro: a chamada repetida não duplica nada. Espere o Retry-After
INTERNAL_ERROR500Erro inesperado no servidor

Códigos de Merchants, Enrollments e Uso por merchant.

CódigoHTTPUso
KYB_NOT_APPROVED403O cadastro da sua empresa ainda não foi aprovado: as escritas ficam bloqueadas até a aprovação
COMPANY_NOT_ACTIVE403A empresa não está ativa
FIELD_REQUIRED422Campo obrigatório faltando (params.field)
FIELD_TOO_LONG422Campo acima do limite (params.field, params.max)
FIELD_INVALID422Valor inválido no campo (params.field)
FIELD_INVALID_OPTION422Valor fora da lista aceita (params.field, params.options)
BATCH_IN_PROGRESS429Outro lote da sua empresa (do mesmo tipo) ainda está sendo gravado. Espere o Retry-After
MERCHANT_DUPLICATE409Outro merchant seu já tem o nome (params.merchant_id)
MERCHANT_REF_CONFLICT409merchant_ref só diferente do gravado em maiúsculas ou acentos
MERCHANT_REF_TAKEN409Outro merchant seu já usa o merchant_ref
MERCHANT_REF_IMMUTABLE409O merchant_ref não se troca depois de gravado
MERCHANT_HAS_HISTORY409Merchant com dado ligado não se apaga: grave status: "inactive" e peça a desativação dos enrollments
MERCHANT_REF_DUPLICATE_IN_BATCH422merchant_ref repetido no mesmo lote
MERCHANT_NAME_DUPLICATE_IN_BATCH422name repetido no mesmo lote
ENROLLMENT_NOT_FOUND404Enrollment inexistente
ENROLLMENT_DUPLICATE409Identificador já em uso na plataforma
ENROLLMENT_PREVIOUSLY_REJECTED409Identificador recusado antes; mande retry_rejected: true para pedir de novo
ENROLLMENT_DUPLICATE_IN_BATCH422Identificador repetido no mesmo lote
ENROLLMENT_BATCH_INVALID422Lote tudo ou nada com item recusado; nada foi gravado (details.errors)
ENROLLMENT_NO_PRODUCT422Nenhum produto pedido
ENROLLMENT_PENDING_LIMIT42220.000 enrollments esperando aprovação na sua empresa
ENROLLMENT_NOTHING_TO_DEACTIVATE422Nenhum produto ativo para desativar
DESCRIPTOR_LOOKS_LIKE_BIN_CAID422O descriptor parece um BIN/CAID: peça como bin_caid
DESCRIPTOR_PREFIX_TOO_SHORT422“Começa com” com menos de 5 caracteres
BIN_INVALID422bin fora de 6 a 10 dígitos
PROVIDER_UNAVAILABLE422O produto não aceita esse tipo de enrollment
MERCHANT_INCOMPLETE_FOR_PREVENTION422Falta cadastro no merchant para a Prevenção (params.fields)
USAGE_CYCLE_NOT_FOUND404Nenhum ciclo de cobrança fechado começa no mês pedido

Todas as rotas compartilham um limite de 100 requisições por minuto por IP, inclusive as que respondem 401 por credencial inválida. A exceção são as rotas de captura pelo navegador, que não contam nos 100: o envio de evento tem teto próprio de 120 por minuto e a configuração do snippet, de 300 por minuto, as duas contadas por IP e token. O script rapid.js do snippet também fica fora, com teto próprio de 300 por minuto por IP.

Ao ultrapassar, a API retorna:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 15
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded, retry in 15 seconds"
}
}

Use o Retry-After. Ele diz, em segundos, quanto falta para a janela virar, e a mensagem repete o mesmo número. Esperar exatamente isso é melhor que chutar: espera progressiva cega pode tentar antes da hora (e tomar outro 429) ou esperar mais que o necessário.

Além dos 100 por IP, algumas rotas têm limite por empresa, contado pela credencial:

RotasLimite
Escritas de merchants e enrollments (POST, PATCH, DELETE; cada lote conta uma)60 por minuto
Uso por merchant10 por minuto
Lotes de merchants e de enrollments1 de cada tipo em andamento (429 BATCH_IN_PROGRESS, Retry-After: 5)

Ao passar do limite por minuto, a resposta é o mesmo 429 RATE_LIMIT_EXCEEDED, com Retry-After.

Os headers X-RateLimit-* vêm em todas as respostas, não só no 429, então você pode se antecipar: quando X-RateLimit-Remaining chegar perto de zero, segure o envio em vez de esperar o erro. Em envio de volume, prefira o envio em lote, que manda até 1000 transações numa requisição e gasta uma unidade do limite.

Erros 5xx geralmente são transitórios. Retente aumentando o intervalo entre as tentativas. Quando a resposta traz Retry-After (os 503 trazem), espere esse tempo. Em merchants e enrollments, o 503 SERVICE_UNAVAILABLE pode chegar depois de a escrita ter sido gravada: repetir a mesma chamada é seguro, porque ela não duplica nada (volta unchanged ou existing). Não retente os demais 4xx: eles indicam erro no seu lado e vão falhar de novo. A exceção é o 429: espere o tempo do Retry-After e repita (ver Rate limit).