Códigos HTTP das respostas
Entenda os códigos HTTP, os detalhes opcionais de validação e os erros de recurso não encontrado na API Raims.
Use o código HTTP junto ao corpo da resposta para identificar o resultado de
uma requisição. Um mesmo código HTTP pode representar erros diferentes;
confira também error.code, error.message e error.details, quando presente.
- respostas
2xxindicam sucesso; - respostas
4xxindicam problemas relacionados à requisição, autenticação, autorização, recurso ou limites; - respostas
5xxindicam falha no processamento pela Raims.
Decidir como continuar
Comece pelo status HTTP e pelo código estável. Estes caminhos ajudam a decidir se você deve corrigir a entrada, acompanhar um recurso ou conferir um resultado que ainda não conhece:
| O que você recebeu | Conferência antes da próxima requisição |
|---|---|
400 INVALID_FIELDS | Use cada field e code de error.details para corrigir os dados. |
401 ou 403 | Confira credencial, acesso e ambiente. Repetir os mesmos dados não altera a autorização. |
202 | Guarde o ID e acompanhe o recurso indicado pelo endpoint. O aceite ainda não confirma a conclusão. |
409 de condição do recurso | Leia error.code, consulte o estado atual e siga a referência desse endpoint. |
429 | Aguarde Retry-After, quando presente, e ajuste a frequência. |
Falha de conexão ou 5xx após uma escrita | Confira se o efeito foi aplicado. Se fizer retry da mesma intenção protegida, conserve a chave de idempotência. |
Para obter os campos inválidos sem depender do texto das mensagens, sua aplicação pode separar os identificadores retornados assim:
const invalidFields =
status === 400 && response.error?.code === 'INVALID_FIELDS'
? (response.error.details ?? []).map(({ field, code }) => ({ field, code }))
: [];response representa o corpo JSON recebido. Preserve caminhos como
identifiers[2]; eles apontam para o item exato a corrigir. A aplicação
define a mensagem que apresenta à pessoa.
Códigos das respostas
| Código HTTP | O que indica | Como tratar |
|---|---|---|
200 OK | A requisição foi processada com sucesso. | Interprete o corpo conforme o endpoint utilizado. |
201 Created | Um recurso foi criado. | Armazene o identificador retornado para reconhecer o recurso nas próximas requisições. |
202 Accepted | A requisição foi aceita, mas o resultado ainda não foi confirmado. | Guarde o identificador e acompanhe o recurso indicado pelo endpoint antes de repetir a solicitação. |
400 Bad Request | Os dados da requisição estão inválidos ou incompletos. | Consulte a mensagem e os campos indicados na resposta para corrigir a requisição. |
401 Unauthorized | A credencial está ausente, inválida ou não pode ser usada. | Confira o header Authorization: Bearer, a credencial e, em uma sessão OAuth, a necessidade de renovar o acesso ou autorizar novamente. |
403 Forbidden | O acesso foi recusado por uma condição da empresa, uma restrição de IP ou uma regra de autorização. | Confira error.code, a situação da conta, as permissões e os IPs permitidos pela chave. O console da documentação aceita somente chaves de Sandbox. |
404 Not Found | A URL ou o recurso solicitado não foi encontrado. | Confira o método, o caminho e o identificador utilizados. |
405 Method Not Allowed | O método HTTP não é aceito nessa rota. | Use o método indicado para a requisição. O header Allow, quando presente, informa os métodos aceitos. |
409 Conflict | A condição atual do recurso ou outra solicitação em andamento impede o processamento do pedido. | Consulte error.code e error.message. Corrija a condição indicada; para uma solicitação em andamento, aguarde Retry-After, quando presente, antes de repetir. |
413 Payload Too Large | O corpo excede o limite permitido para a requisição. | Reduza o corpo enviado e respeite o limite documentado para o endpoint. |
415 Unsupported Media Type | O formato do corpo não é aceito. | Para requisições com corpo JSON, envie Content-Type: application/json. |
422 Unprocessable Entity | A solicitação não pôde ser processada nas condições informadas. | Confira error.code e error.message antes de reenviar o pedido. |
429 Too Many Requests | O limite ou o intervalo de espera da requisição foi atingido. | Aguarde os segundos informados em Retry-After, quando presente, antes de tentar novamente. |
500 Internal Server Error | Uma falha interna impediu a conclusão normal da resposta. | Confira o resultado da requisição antes de repetir uma solicitação que cria ou altera dados. |
502 Bad Gateway | Um serviço de pagamento recusou a solicitação. | Confira o resultado e o código de erro antes de decidir sobre outro pedido. |
503 Service Unavailable | Um serviço necessário está temporariamente indisponível. | Aguarde antes de tentar novamente e confira o resultado de requisições que possam ter sido processadas. |
As páginas dos endpoints apresentam os sucessos, as validações e os erros específicos da requisição, inclusive quando usam um código HTTP descrito aqui. Consulte a seção Respostas do endpoint para conhecer suas condições e exemplos. Os erros gerais desta página também podem ocorrer nesses endpoints, mesmo quando não aparecem novamente em Respostas.
409 REQUEST_IN_PROGRESS indica que outra solicitação ainda está sendo processada.
Aguarde Retry-After, quando presente, antes de repetir o pedido.
Permissões da chave de API
403 API_KEY_PERMISSION_DENIED indica que a chave não tem acesso ao recurso
ou à operação solicitada. Revise a seleção em Integração / Chaves de API /
Editar permissões com uma pessoa autorizada a editar chaves. Selecione a
ação correspondente ao pedido; criar, consultar, editar e remover são
permissões independentes. Repetir a chamada sem mudar o acesso não resolve a recusa.
Consulte Permissões da chave.
Ambiente nas requisições OAuth
400 OAUTH_ENVIRONMENT_REQUIRED exige informar X-Raims-Environment em uma
chamada OAuth. 400 OAUTH_ENVIRONMENT_INVALID indica um valor inválido ou
repetido. Informe um único ambiente aceito pelo endpoint e autorizado para
a conexão OAuth. Consulte a referência do recurso para conferir os ambientes
disponíveis.
403 OAUTH_ENVIRONMENT_FORBIDDEN indica que a conexão não tem acesso ao
ambiente selecionado. 403 OAUTH_SCOPE_FORBIDDEN indica uma requisição fora
das permissões concedidas. Confira a autorização antes de tentar novamente.
Com chave de API, o ambiente é definido pela própria chave. Consulte
Autenticação.
Acesso bloqueado pela situação da empresa
403 COMPANY_STATUS_RESTRICTED indica que a situação da empresa impede o
acesso à API. A mensagem identifica a condição e orienta o próximo passo:
| Situação | Acesso à API | Como proceder |
|---|---|---|
| Empresa suspensa | Bloqueado em Produção e Sandbox. | Contate o SAC em sac@raims.com. |
| Conta encerrada | Bloqueado em Produção e Sandbox. | Contate o SAC em sac@raims.com se precisar de ajuda. |
| Cadastro pendente | Bloqueado em Produção. Sandbox permanece permitido, sujeito às demais regras. | Consulte a situação do cadastro no Dashboard. |
Por exemplo, uma empresa suspensa recebe:
Empresa suspensa
{
"error": {
"code": "COMPANY_STATUS_RESTRICTED",
"message": "Your company is suspended and cannot access the API. Contact our support team at sac@raims.com for assistance."
}
}O contato para essas solicitações da conta é o SAC, conforme os canais de atendimento da Raims. O erro mantém o mesmo código nas situações acima; use a mensagem para diagnóstico humano, sem comparar seu texto na lógica da integração.
Formato dos erros
Os erros da API são retornados em JSON, no objeto error, com code e message.
details é opcional: aparece quando a resposta precisa identificar um campo
inválido ou uma referência enviada no corpo que não foi encontrada. Cada
detalhe informa onde corrigir a requisição e explica o motivo.
Erros gerais de autenticação, autorização, conflito, limite, rota, JSON
malformado, tamanho ou mídia usam somente código e mensagem. A ausência de details é normal.
Por exemplo, uma chave ausente ou inválida recebe:
Recuperar saldo atual
{
"error": {
"code": "UNAUTHORIZED",
"message": "Provide a valid API key or OAuth access token in the Authorization: Bearer header."
}
}As mensagens em error.message e error.details[].message são escritas em
inglês. A documentação explica as condições e como tratá-las em português.
Identifique o erro pelo status HTTP e por error.code. Para corrigir campos,
use também error.details[].field e error.details[].code. Nunca compare o
texto das mensagens na lógica da integração: ele pode mudar sem alterar o
significado dos códigos. Seu sistema pode usar esses códigos para apresentar
uma mensagem no idioma do cliente.
Em validações de campos, error.message resume a categoria do erro.
error.details mantém cada campo ou item da lista com seu código e sua
explicação, sem repetir esse conteúdo no resumo. Confira todos os detalhes
antes de reenviar.
Como localizar o problema
Cada item de error.details informa:
| Campo | Como usar |
|---|---|
field | Identifica o campo enviado, incluindo o caminho quando ele pertence a um objeto ou a um item de lista. |
code | Identifica a condição para tratar o erro no seu sistema. |
message | Explica em inglês o problema naquele campo. |
Por exemplo, customer_id identifica o cliente da cobrança; id identifica
o recurso informado no caminho da URL. O campo $ representa o corpo JSON
inteiro quando a validação exige outro tipo, como um objeto em vez de array.
Parâmetros de consulta e rota usam seus nomes públicos. Confira todos os
detalhes recebidos antes de reenviar a requisição.
Exemplo de resposta HTTP 400
Campo obrigatório ausente
{
"error": {
"code": "INVALID_FIELDS",
"message": "One or more request fields are invalid.",
"details": [
{
"field": "tax_id",
"code": "REQUIRED",
"message": "tax_id is required."
}
]
}
}REQUIRED indica um campo obrigatório ausente; MIN_LENGTH indica
um valor abaixo do tamanho mínimo; MAX_LENGTH indica
que o tamanho permitido foi ultrapassado. INVALID_TAXID indica um CPF ou
CNPJ inválido; INVALID_EMAIL indica um e-mail inválido. MAX_ITEMS indica
que uma coleção contém mais itens do que o limite aceito pela requisição.
MUTUALLY_EXCLUSIVE indica campos que não podem ser preenchidos juntos,
como after e before na paginação. Envie somente um deles.
Confira também as regras da requisição.
Recurso não encontrado
Um 404 NOT_FOUND pode indicar que o recurso consultado não está disponível
para a empresa e o ambiente autenticado. Ao consultar um cliente por id, a
mensagem identifica o recurso, sem detalhes adicionais:
Recuperar um único cliente
{
"error": {
"code": "NOT_FOUND",
"message": "The customer specified by id was not found."
}
}Quando a referência foi enviada no corpo, como customer_id ao criar uma
cobrança, a resposta usa details para identificar o campo a conferir:
Criar nova cobrança
{
"error": {
"code": "NOT_FOUND",
"message": "A referenced resource was not found.",
"details": [
{
"field": "customer_id",
"code": "NOT_FOUND",
"message": "The customer specified by customer_id was not found."
}
]
}
}Confira o identificador e use a chave da empresa e do ambiente em que o recurso foi cadastrado. Essa resposta não confirma a existência do recurso em outra conta ou ambiente. Uma listagem sem resultados continua retornando uma lista vazia, conforme as regras do endpoint.
Uma URL desconhecida também retorna 404, mas sua mensagem indica o método
e o caminho que não foram reconhecidos. Nesse caso, confira o endereço do
endpoint na referência.
JSON malformado e campos inválidos
INVALID_JSON indica que o corpo não pôde ser interpretado como JSON, por
exemplo, por uma vírgula ou aspas fora do lugar. Corrija a estrutura do corpo
antes de reenviar a requisição.
Quando o JSON está bem formado, mas contém campos desconhecidos, repetidos ou
com um tipo incompatível, a resposta usa INVALID_FIELDS e identifica o problema
em error.details:
Código em details | O que corrigir |
|---|---|
UNKNOWN_FIELD | Remova o campo indicado ou corrija seu nome conforme o endpoint. |
DUPLICATE_FIELD | Envie o campo uma única vez no mesmo objeto. |
INVALID_TYPE | Use o tipo indicado no endpoint, como uma string para tax_id. |
Por exemplo, enviar tax_id como número em vez de string retorna:
Tipo incompatível
{
"error": {
"code": "INVALID_FIELDS",
"message": "One or more request fields are invalid.",
"details": [
{
"field": "tax_id",
"code": "INVALID_TYPE",
"message": "tax_id must be a JSON string."
}
]
}
}Quando o endpoint exige um objeto e recebe outro tipo de JSON, como um array,
field usa $ para indicar o corpo inteiro, com o código INVALID_TYPE.
Campos obrigatórios ausentes e valores que não atendem às regras do endpoint
continuam usando INVALID_FIELDS, com os códigos de validação correspondentes.
Quando error.details indicar field: tax_id e code: INVALID_TAXID,
consulte Validação de CPF e CNPJ.
O guia explica como conferir o documento antes da requisição e orientar sua
correção no sistema da integração.
Conflitos de estado e condições de uso
Um erro de estado informa a condição atual do recurso e os estados aceitos para a ação. O mesmo código pode ter explicações diferentes conforme a condição que impediu a requisição.
Use error.code para tratar o motivo e leia error.message para entender a
condição observada. Confira os exemplos específicos em Respostas e consulte
o recurso antes de tentar novamente. Estar em um estado aceito não garante
que as outras condições da requisição estejam atendidas.
Alguns endpoints oferecem consultas para conferir a elegibilidade ou a disponibilidade de um recurso. Consulte a referência do endpoint para identificar a consulta e as condições aplicáveis.
Limites de requisições
429 RATE_LIMITED indica uma recusa por excesso de requisições. Aguarde
Retry-After e ajuste a frequência ou a concorrência conforme
Raims-Rate-Limited-Reason. Alguns endpoints têm regras e intervalos próprios,
descritos na sua referência.
O guia de rate limiting explica os limites por empresa e ambiente, os motivos, as novas tentativas e um exemplo de consulta com fila.
Falhas temporárias e resultados incertos
Uma resposta 503 pode indicar indisponibilidade temporária ao autenticar,
consultar dados ou usar um serviço de pagamento. Confira error.code e
error.message para identificar a causa informada.
503 OAUTH_AUTHORIZATION_UNAVAILABLE indica que o acesso atual não pôde ser
confirmado. 503 OAUTH_AUTHORIZATION_CHANGED informa que a autorização mudou
durante a requisição e o resultado pode já ter sido aplicado. Depois de
regularizar o acesso, consulte o recurso antes de repetir uma escrita. Ao
retomar a requisição pela mesma conexão, preserve a Idempotency-Key original.
Se precisar autorizar uma nova conexão, confira o resultado da tentativa
anterior antes de enviar outra requisição.
503 RATE_LIMIT_STORE_UNAVAILABLE indica que a API não pôde aceitar a
requisição e ela não foi executada. Aguarde Retry-After antes de tentar
novamente.
Mesmo com uma resposta 500, 502 ou 503, ou uma conexão interrompida, a
requisição pode ter sido processada. Antes de repetir uma chamada que cria ou
altera dados, confira o resultado e siga as orientações do endpoint. Evite
repetir requisições continuamente durante uma falha.
Quando a resposta trouxer Retry-After, aguarde o número de segundos indicado.
Esse header não aparece em todas as falhas. Transient-Error: true, quando
presente, indica uma falha temporária. Você ainda precisa conferir o resultado
antes de repetir uma requisição que cria ou altera dados.
Ao pedir ajuda ao suporte, informe o método, o caminho, o horário, o status HTTP e o código de erro. Remova chaves de API e dados pessoais dos exemplos compartilhados.