HTTP response codes

Use the HTTP code together with the response body to identify a request's result. The same HTTP code can represent different errors; also check error.code, error.message and error.details, when present.

• 2xx responses indicate success;
• 4xx responses indicate problems with the request, authentication, authorization, resource or limits;
• 5xx responses indicate a processing failure on the Raims side.

Response codes

Endpoint pages show successes, validation errors and request-specific errors, including those using an HTTP code described here. See the endpoint's Responses section for its conditions and examples. The general errors on this page can also occur on these endpoints, even when they are not repeated in Responses.

409 REQUEST_IN_PROGRESS indicates that another request is still being processed. Wait for Retry-After, when present, before retrying.

Access blocked by company status

403 COMPANY_STATUS_RESTRICTED indicates that the company's status prevents API access. The message identifies the condition and gives the next step:

For example, a suspended company receives:

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

Contact customer support for these account requests, as listed in the Raims support channels. The error keeps the same code for the statuses above; use the message for human diagnosis, without comparing its text in integration logic.

Error format

API errors are returned as JSON in the error object, with code and message. details is optional: it appears when the response needs to identify an invalid field or a reference sent in the body that was not found. Each detail shows where to correct the request and explains why.

General authentication, authorization, conflict, limit, route, malformed JSON, size and media errors use only a code and message. It is normal for details to be absent. For example, a missing or invalid key receives:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide a valid API key in the Authorization: Bearer header."
  }
}

Messages in error.message and error.details[].message are written in English. The documentation explains the conditions and how to handle them.

Identify the error by its HTTP status and error.code. To correct fields, also use error.details[].field and error.details[].code. Never compare message text in integration logic: it may change without changing the meaning of the codes. Your system can use these codes to display a message in the customer's language.

For field validation, error.message summarizes the error category. error.details keeps each field or list item with its code and explanation, without repeating that content in the summary. Check every detail before submitting again.

Locating the problem

Each item in error.details contains:

For example, customer_id identifies the charge's customer; id identifies the resource in the URL path. The $ field represents the entire JSON body when validation requires a different type, such as an object instead of an array. Query and path parameters use their public names. Check every detail received before submitting the request again.

Example HTTP 400 response

{
  "error": {
    "code": "INVALID_FIELDS",
    "message": "One or more request fields are invalid.",
    "details": [
      {
        "field": "tax_id",
        "code": "REQUIRED",
        "message": "tax_id is required."
      }
    ]
  }
}

REQUIRED indicates a missing required field; MIN_LENGTH indicates a value below the minimum length; MAX_LENGTH indicates that the allowed length was exceeded. INVALID_TAXID indicates an invalid CPF or CNPJ; INVALID_EMAIL indicates an invalid email address. MAX_ITEMS indicates that a collection has more items than the request allows. MUTUALLY_EXCLUSIVE indicates fields that cannot both have values, such as after and before in pagination. Send only one of them. Also check the request's rules.

Resource not found

A 404 NOT_FOUND can indicate that the queried resource is not available to the key's company and environment. When querying a customer by id, the message identifies the resource without additional details:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The customer specified by id was not found."
  }
}

When the reference was sent in the body, such as customer_id when creating a charge, the response uses details to identify the field to check:

{
  "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."
      }
    ]
  }
}

Check the identifier and use the key for the company and environment where the resource was registered. This response does not confirm that the resource exists in another account or environment. A listing with no results still returns an empty list, according to the endpoint's rules.

An unknown URL also returns 404, but its message identifies the method and path that were not recognized. In that case, check the endpoint's address in the reference.

Malformed JSON and invalid fields

INVALID_JSON indicates that the body could not be parsed as JSON, for example because of a misplaced comma or quotation mark. Correct the body structure before submitting the request again.

When the JSON is well formed but contains unknown or repeated fields, or fields with an incompatible type, the response uses INVALID_FIELDS and identifies the problem in error.details:

For example, sending tax_id as a number instead of a string returns:

{
  "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."
      }
    ]
  }
}

When an endpoint requires an object and receives another JSON type, such as an array, field uses $ to indicate the entire body, with code INVALID_TYPE. Missing required fields and values that do not meet the endpoint's rules still use INVALID_FIELDS, with the corresponding validation codes.

When error.details indicates field: tax_id and code: INVALID_TAXID, see CPF and CNPJ validation. The guide explains how to check the tax ID before the request and guide its correction in the integration's system.

State conflicts and usage conditions

A state error reports the resource's current condition and the accepted states for the action. For example, a paid charge cannot be edited or revoked. The same code can have different explanations when the restriction comes from the due date, payment method, environment or a request in progress.

Use error.code to handle the cause, and read error.message to understand the observed condition. Check the specific examples in Responses and query the resource before trying again. Being in an accepted state does not guarantee that the request's other conditions are met.

For refunds, the eligibility query reports the current restriction and remaining amount. For links, the individual query reports is_payable and unavailable_reason. These queries do not start a payment or refund.

Temporary failures and uncertain results

A 503 response can indicate temporary unavailability while authenticating, querying data or using a payment service. The codes STORE_UNAVAILABLE, AUTHENTICATION_STORE_UNAVAILABLE, CLIENT_SEARCH_INDEX_UNAVAILABLE, CHARGE_SEARCH_INDEX_UNAVAILABLE and PAYMENT_PROVIDER_UNAVAILABLE follow the general guidance for this status, as do PIX_GENERATION_UNAVAILABLE, BOLETO_GENERATION_UNAVAILABLE, PIX_REFUND_PROVIDER_UNAVAILABLE, PIX_REFUND_PROVIDER_REQUEST_INVALID, PIX_WITHDRAWAL_PROVIDER_UNAVAILABLE and PIX_WITHDRAWAL_UNAVAILABLE. Check error.code and error.message to identify the reported cause.

For webhooks, WEBHOOK_CONFIGURATION_UNAVAILABLE, WEBHOOK_DELIVERIES_UNAVAILABLE and WEBHOOK_TEST_UNAVAILABLE also follow this guidance. Wait before querying again. If the failure occurs while changing a registration, sending a test or resending an event, check the configuration or deliveries before repeating the request.

For withdrawal requests, check the history before requesting another withdrawal. If you receive 409 PIX_WITHDRAWAL_RESULT_UNKNOWN, query the withdrawal indicated in Location and follow the same identifier until the result is clear.

502 PIX_REFUND_PROVIDER_REJECTED reports that the payment service rejected the refund request. Check the request and charge eligibility before deciding whether to submit another request. Do not repeat the same request continuously.

Even with a 500, 502 or 503 response, or connection loss, the request may have been processed. Before repeating a call that creates or changes data, check the result and follow the endpoint's guidance. Avoid repeating requests continuously during a failure.

When the response includes Retry-After, wait the indicated number of seconds. This header does not appear in every failure. Transient-Error: true, when present, indicates a temporary failure. You still need to check the result before repeating a request that creates or changes data.

When asking support for help, provide the method, path, time, HTTP status and error code. Remove API keys and personal data from shared examples.