Códigos de resposta
Referência dos códigos HTTP usados por toda a API da Rapid.
Códigos de sucesso
Seção intitulada “Códigos de sucesso”| Código | Significado |
|---|---|
| 200 | Sucesso com corpo |
| 201 | Recurso criado |
| 204 | Sucesso sem corpo (ex.: Remover merchant) |
Códigos de erro do cliente
Seção intitulada “Códigos de erro do cliente”| Código | Significado |
|---|---|
| 400 | Corpo que não é JSON válido (INVALID_JSON) |
| 401 | Credenciais ausentes ou inválidas |
| 403 | Empresa bloqueada, cadastro da empresa ainda não aprovado (KYB_NOT_APPROVED), ou produto necessário não ativo (PRODUCT_NOT_ACTIVE) |
| 404 | Recurso não encontrado |
| 405 | Operação não permitida (TRANSACTION_DELETE_NOT_ALLOWED) |
| 409 | Conflito (duplicata, atualização de recurso imutável) |
| 413 | Corpo acima do tamanho máximo (PAYLOAD_TOO_LARGE) |
| 422 | Erro de validação |
| 429 | Muitas requisições (rate limit) |
Códigos de erro do servidor
Seção intitulada “Códigos de erro do servidor”| Código | Significado |
|---|---|
| 500 | Erro interno (INTERNAL_ERROR), retentativa recomendada |
| 503 | Indisponibilidade temporária (SERVICE_UNAVAILABLE, CAPTURE_TEMPORARILY_UNAVAILABLE), com Retry-After |
Formato do corpo de erro
Seção intitulada “Formato do corpo de erro”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 listaerrorscomindex,code,messageeparamsde cada item recusado.
Quem lê só code e message não precisa mudar nada.
Códigos semânticos mais comuns
Seção intitulada “Códigos semânticos mais comuns”| Código | HTTP | Uso |
|---|---|---|
INVALID_JSON | 400 | O corpo não é um JSON válido |
UNAUTHORIZED | 401 | Credenciais ausentes ou inválidas |
COMPANY_BLOCKED | 403 | Empresa bloqueada |
PRODUCT_NOT_ACTIVE | 403 | Criaçã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_ERROR | 422 | Um ou mais campos inválidos |
NOT_FOUND | 404 | O endereço não existe na API (caminho com erro de digitação, barra sobrando no fim) |
TRANSACTION_NOT_FOUND | 404 | Transação inexistente |
TRANSACTION_DUPLICATE | 409 | external_source + external_id já cadastrado |
TRANSACTION_IMMUTABLE | 409 | Transação já utilizada, não pode ser atualizada |
TRANSACTION_DELETE_NOT_ALLOWED | 405 | Transações não podem ser apagadas (ver Deletar transação) |
MERCHANT_NOT_FOUND | 404 | Merchant inexistente |
ALERT_NOT_FOUND | 404 | Alerta inexistente |
ALERT_INVALID_STATUS | 422 | Status inválido, ou transição não permitida (prazo, expiração ou status já definitivo) |
PAYLOAD_TOO_LARGE | 413 | Corpo 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_EXCEEDED | 429 | Limite de requisições excedido (ver abaixo) |
ORIGIN_NOT_ALLOWED | 403 | Evento 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_EVENTS | 429 | Eventos de captura demais esperando a transação aparecer (ver Limite de chamadas) |
CAPTURE_TEMPORARILY_UNAVAILABLE | 503 | Captura temporariamente indisponível. Reenvie o evento depois do Retry-After, com o mesmo event_id |
SERVICE_UNAVAILABLE | 503 | Indisponibilidade temporária em merchants, enrollments e uso. Repetir é seguro: a chamada repetida não duplica nada. Espere o Retry-After |
INTERNAL_ERROR | 500 | Erro inesperado no servidor |
Merchants, enrollments e uso
Seção intitulada “Merchants, enrollments e uso”Códigos de Merchants, Enrollments e Uso por merchant.
| Código | HTTP | Uso |
|---|---|---|
KYB_NOT_APPROVED | 403 | O cadastro da sua empresa ainda não foi aprovado: as escritas ficam bloqueadas até a aprovação |
COMPANY_NOT_ACTIVE | 403 | A empresa não está ativa |
FIELD_REQUIRED | 422 | Campo obrigatório faltando (params.field) |
FIELD_TOO_LONG | 422 | Campo acima do limite (params.field, params.max) |
FIELD_INVALID | 422 | Valor inválido no campo (params.field) |
FIELD_INVALID_OPTION | 422 | Valor fora da lista aceita (params.field, params.options) |
BATCH_IN_PROGRESS | 429 | Outro lote da sua empresa (do mesmo tipo) ainda está sendo gravado. Espere o Retry-After |
MERCHANT_DUPLICATE | 409 | Outro merchant seu já tem o nome (params.merchant_id) |
MERCHANT_REF_CONFLICT | 409 | merchant_ref só diferente do gravado em maiúsculas ou acentos |
MERCHANT_REF_TAKEN | 409 | Outro merchant seu já usa o merchant_ref |
MERCHANT_REF_IMMUTABLE | 409 | O merchant_ref não se troca depois de gravado |
MERCHANT_HAS_HISTORY | 409 | Merchant com dado ligado não se apaga: grave status: "inactive" e peça a desativação dos enrollments |
MERCHANT_REF_DUPLICATE_IN_BATCH | 422 | merchant_ref repetido no mesmo lote |
MERCHANT_NAME_DUPLICATE_IN_BATCH | 422 | name repetido no mesmo lote |
ENROLLMENT_NOT_FOUND | 404 | Enrollment inexistente |
ENROLLMENT_DUPLICATE | 409 | Identificador já em uso na plataforma |
ENROLLMENT_PREVIOUSLY_REJECTED | 409 | Identificador recusado antes; mande retry_rejected: true para pedir de novo |
ENROLLMENT_DUPLICATE_IN_BATCH | 422 | Identificador repetido no mesmo lote |
ENROLLMENT_BATCH_INVALID | 422 | Lote tudo ou nada com item recusado; nada foi gravado (details.errors) |
ENROLLMENT_NO_PRODUCT | 422 | Nenhum produto pedido |
ENROLLMENT_PENDING_LIMIT | 422 | 20.000 enrollments esperando aprovação na sua empresa |
ENROLLMENT_NOTHING_TO_DEACTIVATE | 422 | Nenhum produto ativo para desativar |
DESCRIPTOR_LOOKS_LIKE_BIN_CAID | 422 | O descriptor parece um BIN/CAID: peça como bin_caid |
DESCRIPTOR_PREFIX_TOO_SHORT | 422 | “Começa com” com menos de 5 caracteres |
BIN_INVALID | 422 | bin fora de 6 a 10 dígitos |
PROVIDER_UNAVAILABLE | 422 | O produto não aceita esse tipo de enrollment |
MERCHANT_INCOMPLETE_FOR_PREVENTION | 422 | Falta cadastro no merchant para a Prevenção (params.fields) |
USAGE_CYCLE_NOT_FOUND | 404 | Nenhum ciclo de cobrança fechado começa no mês pedido |
Rate limit
Seção intitulada “Rate limit”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 RequestsRetry-After: 15X-RateLimit-Limit: 100X-RateLimit-Remaining: 0X-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.
Limites por empresa
Seção intitulada “Limites por empresa”Além dos 100 por IP, algumas rotas têm limite por empresa, contado pela credencial:
| Rotas | Limite |
|---|---|
Escritas de merchants e enrollments (POST, PATCH, DELETE; cada lote conta uma) | 60 por minuto |
| Uso por merchant | 10 por minuto |
| Lotes de merchants e de enrollments | 1 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.
Retry em erros 5xx
Seção intitulada “Retry em erros 5xx”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).