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.
2xxresponses indicate success;4xxresponses indicate problems with the request, authentication, authorization, resource or limits;5xxresponses 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 received | What to check before the next request |
|---|---|
400 INVALID_FIELDS | Use each field and code in error.details to correct the data. |
401 or 403 | Check the credential, access and environment. Retrying the same data does not change authorization. |
202 | Keep the ID and track the resource specified by the endpoint. Acceptance does not yet confirm completion. |
409 for a resource condition | Read error.code, query the current state and follow that endpoint's reference. |
429 | Wait for Retry-After, when present, and adjust the request frequency. |
Connection failure or 5xx after a write | Check 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:
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 code | What it indicates | How to handle it |
|---|---|---|
200 OK | The request was processed successfully. | Interpret the body according to the endpoint used. |
201 Created | A resource was created. | Store the returned identifier to recognize the resource in future requests. |
202 Accepted | The 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 Request | The request data is invalid or incomplete. | Check the message and fields indicated in the response to correct the request. |
401 Unauthorized | The 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 Forbidden | Access 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 Found | The requested URL or resource was not found. | Check the method, path and identifier used. |
405 Method Not Allowed | The 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 Conflict | The 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 Large | The body exceeds the request's allowed size. | Reduce the body sent and respect the endpoint's documented limit. |
415 Unsupported Media Type | The body format is not accepted. | For requests with a JSON body, send Content-Type: application/json. |
422 Unprocessable Entity | The request could not be processed under the supplied conditions. | Check error.code and error.message before submitting it again. |
429 Too Many Requests | The request limit or waiting interval was reached. | Wait the number of seconds in Retry-After, when present, before trying again. |
500 Internal Server Error | An internal failure prevented normal completion of the response. | Check the result before repeating a request that creates or changes data. |
502 Bad Gateway | A payment service rejected the request. | Check the result and error code before deciding whether to submit another request. |
503 Service Unavailable | A 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:
| Status | API access | What to do |
|---|---|---|
| Suspended company | Blocked in Production and Sandbox. | Contact customer support at sac@raims.com. |
| Closed account | Blocked in Production and Sandbox. | Contact customer support at sac@raims.com if you need help. |
| Pending registration | Blocked in Production. Sandbox remains allowed, subject to the other rules. | Check the registration status in the Dashboard. |
For example, a suspended company receives:
Company suspended
{
"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:
Retrieve current balance
{
"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:
| Field | How to use it |
|---|---|
field | Identifies the submitted field, including its path when it belongs to an object or list item. |
code | Identifies the condition so your system can handle the error. |
message | Explains 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
Required field missing
{
"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:
Retrieve a single customer
{
"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:
Create a new charge
{
"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 details | What to correct |
|---|---|
UNKNOWN_FIELD | Remove the indicated field or correct its name according to the endpoint. |
DUPLICATE_FIELD | Send the field only once in the same object. |
INVALID_TYPE | Use 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:
Incompatible type
{
"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.