API
Checking Raims account

HTTP response codes

Understand HTTP codes, optional validation details and resource not found errors in the Raims API.

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.

Decide what to do next

Start with the HTTP status and stable code. These paths help you decide whether to correct the input, track a resource or check a result you do not yet know:

What you receivedWhat to check before the next request
400 INVALID_FIELDSUse each field and code in error.details to correct the data.
401 or 403Check the credential, access and environment. Retrying the same data does not change authorization.
202Keep the ID and track the resource specified by the endpoint. Acceptance does not yet confirm completion.
409 for a resource conditionRead error.code, query the current state and follow that endpoint's reference.
429Wait for Retry-After, when present, and adjust the request frequency.
Connection failure or 5xx after a writeCheck whether its effect was applied. When retrying the same protected intent, keep the idempotency key.

To obtain invalid fields without depending on message text, your application can extract the returned identifiers like this:

JavaScript
const invalidFields =
  status === 400 && response.error?.code === 'INVALID_FIELDS'
    ? (response.error.details ?? []).map(({ field, code }) => ({ field, code }))
    : [];

response represents the received JSON body. Preserve paths such as identifiers[2]; they point to the exact item to correct. The application defines the message it shows to the person.

Response codes

HTTP codeWhat it indicatesHow to handle it
200 OKThe request was processed successfully.Interpret the body according to the endpoint used.
201 CreatedA resource was created.Store the returned identifier to recognize the resource in future requests.
202 AcceptedThe request was accepted, but its result has not been confirmed yet.Keep the identifier and follow the resource indicated by the endpoint before repeating the request.
400 Bad RequestThe request data is invalid or incomplete.Check the message and fields indicated in the response to correct the request.
401 UnauthorizedThe credential is missing, invalid or cannot be used.Check the Authorization: Bearer header, the credential and, for an OAuth session, whether access needs to be refreshed or authorized again.
403 ForbiddenAccess was denied because of a company condition, an IP restriction or an authorization rule.Check error.code, the account status, and the key's permissions and allowed IPs. The documentation console accepts only Sandbox keys.
404 Not FoundThe requested URL or resource was not found.Check the method, path and identifier used.
405 Method Not AllowedThe HTTP method is not accepted on this route.Use the method specified for the request. The Allow header, when present, lists the accepted methods.
409 ConflictThe current resource condition or another request in progress prevents processing.Check error.code and error.message. Correct the indicated condition; for a request in progress, wait for Retry-After, when present, before retrying.
413 Payload Too LargeThe body exceeds the request's allowed size.Reduce the body sent and respect the endpoint's documented limit.
415 Unsupported Media TypeThe body format is not accepted.For requests with a JSON body, send Content-Type: application/json.
422 Unprocessable EntityThe request could not be processed under the supplied conditions.Check error.code and error.message before submitting it again.
429 Too Many RequestsThe request limit or waiting interval was reached.Wait the number of seconds in Retry-After, when present, before trying again.
500 Internal Server ErrorAn internal failure prevented normal completion of the response.Check the result before repeating a request that creates or changes data.
502 Bad GatewayA payment service rejected the request.Check the result and error code before deciding whether to submit another request.
503 Service UnavailableA required service is temporarily unavailable.Wait before trying again and check the result of requests that may have been processed.

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.

API key permissions

403 API_KEY_PERMISSION_DENIED means the key cannot access the requested resource or operation. Ask someone authorized to edit keys to review the selection in Integration / API keys / Edit permissions. Select the action that matches the request; creating, viewing, updating, and deleting are independent permissions. Repeating the request without changing access does not resolve the denial.

See Key permissions.

Environment in OAuth requests

400 OAUTH_ENVIRONMENT_REQUIRED requires X-Raims-Environment on an OAuth request. 400 OAUTH_ENVIRONMENT_INVALID indicates an invalid or repeated value. Supply exactly one environment accepted by the endpoint and authorized for the OAuth connection. Check the resource reference for supported environments.

403 OAUTH_ENVIRONMENT_FORBIDDEN means the connection cannot access the selected environment. 403 OAUTH_SCOPE_FORBIDDEN means the request is outside the granted permissions. Check the authorization before trying again. With an API key, the key itself determines the environment. See Authentication.

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:

StatusAPI accessWhat to do
Suspended companyBlocked in Production and Sandbox.Contact customer support at sac@raims.com.
Closed accountBlocked in Production and Sandbox.Contact customer support at sac@raims.com if you need help.
Pending registrationBlocked in Production. Sandbox remains allowed, subject to the other rules.Check the registration status in the Dashboard.

For example, a suspended company receives:

HTTP 403 response exampleGET /v1/balances

Company suspended

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

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:

HTTP 401 response exampleGET /v1/balances

Retrieve current balance

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

FieldHow to use it
fieldIdentifies the submitted field, including its path when it belongs to an object or list item.
codeIdentifies the condition so your system can handle the error.
messageExplains the problem with that field in English.

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

HTTP 400 response examplePOST /v1/customers

Required field missing

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

HTTP 404 response exampleGET /v1/customers/{id}

Retrieve a single customer

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

HTTP 404 response examplePOST /v1/charges

Create a new charge

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

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:

Code in detailsWhat to correct
UNKNOWN_FIELDRemove the indicated field or correct its name according to the endpoint.
DUPLICATE_FIELDSend the field only once in the same object.
INVALID_TYPEUse the type specified by the endpoint, such as a string for tax_id.

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

HTTP 400 response examplePOST /v1/customers

Incompatible type

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

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. The same code can have different explanations depending on the condition that prevented the request.

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.

Some endpoints offer queries to check a resource's eligibility or availability. See the endpoint's reference to identify the query and applicable conditions.

Request limits

429 RATE_LIMITED indicates a refusal due to excess requests. Wait for Retry-After and adjust the rate or concurrency according to Raims-Rate-Limited-Reason. Some endpoints have their own rules and waiting intervals, described in their reference.

The rate limiting guide explains the limits per company and environment, reasons, retries and a queued query example.

Temporary failures and uncertain results

A 503 response can indicate temporary unavailability while authenticating, querying data or using a payment service. Check error.code and error.message to identify the reported cause.

503 OAUTH_AUTHORIZATION_UNAVAILABLE means current access could not be confirmed. 503 OAUTH_AUTHORIZATION_CHANGED means authorization changed during the request and the result may already have been applied. After restoring access, query the resource before repeating a write. When resuming through the same connection, keep the original Idempotency-Key. If you need to authorize a new connection, check the previous attempt's result before sending another request.

503 RATE_LIMIT_STORE_UNAVAILABLE indicates that the API could not accept the request and did not execute it. Wait for Retry-After before trying again.

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.