API
Verificando conta Raims

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 2xx indicam sucesso;
  • respostas 4xx indicam problemas relacionados à requisição, autenticação, autorização, recurso ou limites;
  • respostas 5xx indicam 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ê recebeuConferência antes da próxima requisição
400 INVALID_FIELDSUse cada field e code de error.details para corrigir os dados.
401 ou 403Confira credencial, acesso e ambiente. Repetir os mesmos dados não altera a autorização.
202Guarde o ID e acompanhe o recurso indicado pelo endpoint. O aceite ainda não confirma a conclusão.
409 de condição do recursoLeia error.code, consulte o estado atual e siga a referência desse endpoint.
429Aguarde Retry-After, quando presente, e ajuste a frequência.
Falha de conexão ou 5xx após uma escritaConfira 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:

JavaScript
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 HTTPO que indicaComo tratar
200 OKA requisição foi processada com sucesso.Interprete o corpo conforme o endpoint utilizado.
201 CreatedUm recurso foi criado.Armazene o identificador retornado para reconhecer o recurso nas próximas requisições.
202 AcceptedA 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 RequestOs 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 UnauthorizedA 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 ForbiddenO 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 FoundA URL ou o recurso solicitado não foi encontrado.Confira o método, o caminho e o identificador utilizados.
405 Method Not AllowedO 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 ConflictA 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 LargeO corpo excede o limite permitido para a requisição.Reduza o corpo enviado e respeite o limite documentado para o endpoint.
415 Unsupported Media TypeO formato do corpo não é aceito.Para requisições com corpo JSON, envie Content-Type: application/json.
422 Unprocessable EntityA 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 RequestsO 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 ErrorUma 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 GatewayUm 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 UnavailableUm 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çãoAcesso à APIComo proceder
Empresa suspensaBloqueado em Produção e Sandbox.Contate o SAC em sac@raims.com.
Conta encerradaBloqueado em Produção e Sandbox.Contate o SAC em sac@raims.com se precisar de ajuda.
Cadastro pendenteBloqueado em Produção. Sandbox permanece permitido, sujeito às demais regras.Consulte a situação do cadastro no Dashboard.

Por exemplo, uma empresa suspensa recebe:

Exemplo de resposta HTTP 403GET /v1/balances

Empresa suspensa

JSON
{
  "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:

Exemplo de resposta HTTP 401GET /v1/balances

Recuperar saldo atual

JSON
{
  "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:

CampoComo usar
fieldIdentifica o campo enviado, incluindo o caminho quando ele pertence a um objeto ou a um item de lista.
codeIdentifica a condição para tratar o erro no seu sistema.
messageExplica 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

Exemplo de resposta HTTP 400POST /v1/customers

Campo obrigatório ausente

JSON
{
  "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:

Exemplo de resposta HTTP 404GET /v1/customers/{id}

Recuperar um único cliente

JSON
{
  "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:

Exemplo de resposta HTTP 404POST /v1/charges

Criar nova cobrança

JSON
{
  "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 detailsO que corrigir
UNKNOWN_FIELDRemova o campo indicado ou corrija seu nome conforme o endpoint.
DUPLICATE_FIELDEnvie o campo uma única vez no mesmo objeto.
INVALID_TYPEUse o tipo indicado no endpoint, como uma string para tax_id.

Por exemplo, enviar tax_id como número em vez de string retorna:

Exemplo de resposta HTTP 400POST /v1/customers

Tipo incompatível

JSON
{
  "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.