Códigos HTTP das respostas

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.

Códigos das respostas

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.

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:

Por exemplo, uma empresa suspensa recebe:

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

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide a valid API key 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:

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

{
  "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 da chave. Ao consultar um cliente por id, a mensagem identifica o recurso, sem detalhes adicionais:

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

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

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

{
  "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. Por exemplo, uma cobrança paga não pode ser editada nem revogada. O mesmo código pode ter explicações diferentes quando o impedimento vem do vencimento, do meio de pagamento, do ambiente ou de um pedido em andamento.

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.

Para estornos, a consulta de elegibilidade informa o impedimento atual e o valor restante. Para links, a consulta individual informa is_payable e unavailable_reason. Essas consultas não iniciam um pagamento ou estorno.

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. Os códigos STORE_UNAVAILABLE, AUTHENTICATION_STORE_UNAVAILABLE, CLIENT_SEARCH_INDEX_UNAVAILABLE, CHARGE_SEARCH_INDEX_UNAVAILABLE e PAYMENT_PROVIDER_UNAVAILABLE seguem a orientação geral desse status, assim como PIX_GENERATION_UNAVAILABLE, BOLETO_GENERATION_UNAVAILABLE, PIX_REFUND_PROVIDER_UNAVAILABLE, PIX_REFUND_PROVIDER_REQUEST_INVALID, PIX_WITHDRAWAL_PROVIDER_UNAVAILABLE e PIX_WITHDRAWAL_UNAVAILABLE. Confira error.code e error.message para identificar a causa informada.

Nos webhooks, WEBHOOK_CONFIGURATION_UNAVAILABLE, WEBHOOK_DELIVERIES_UNAVAILABLE e WEBHOOK_TEST_UNAVAILABLE também seguem essa orientação. Aguarde antes de consultar novamente. Se a falha ocorrer ao alterar um cadastro, enviar um teste ou reenviar um evento, confira a configuração ou as entregas antes de repetir o pedido.

Nos pedidos de saque, confira o histórico antes de solicitar outra retirada. Se receber 409 PIX_WITHDRAWAL_RESULT_UNKNOWN, consulte o saque indicado em Location e acompanhe o mesmo identificador até esclarecer o resultado.

502 PIX_REFUND_PROVIDER_REJECTED informa que o serviço de pagamento recusou o pedido de estorno. Consulte a solicitação e a elegibilidade da cobrança antes de decidir sobre outro pedido. Não repita a mesma requisição continuamente.

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.