Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Reference of the HTTP codes used across the whole Rapid API.

CodeMeaning
200Success with body
201Resource created
204Success with no body (e.g. Delete merchant)
CodeMeaning
400Body is not valid JSON (INVALID_JSON)
401Missing or invalid credentials
403Company blocked, company registration not approved yet (KYB_NOT_APPROVED), or required product not active (PRODUCT_NOT_ACTIVE)
404Resource not found
405Operation not allowed (TRANSACTION_DELETE_NOT_ALLOWED)
409Conflict (duplicate, update of an immutable resource)
413Body above the maximum size (PAYLOAD_TOO_LARGE)
422Validation error
429Too many requests (rate limit)
CodeMeaning
500Internal error (INTERNAL_ERROR), retry recommended
503Temporarily unavailable (SERVICE_UNAVAILABLE, CAPTURE_TEMPORARILY_UNAVAILABLE), with Retry-After

Every error response has this structure:

{
"error": {
"code": "SEMANTIC_CODE",
"message": "Human-readable description of the error"
}
}

The message is in English and is meant for whoever reads the log: its wording can change. To decide what to do in your code, use the code. The endpoints kept from the previous system respond as they did before.

Some errors also bring params and details, only when they exist:

{
"error": {
"code": "FIELD_TOO_LONG",
"message": "name must be at most 255 characters",
"params": { "field": "name", "max": 255 }
}
}
  • params: the error data, such as the field (field), the limit (max) or the id of the conflicting resource (merchant_id, enrollment_id).
  • details: in a rejected all or nothing batch (ENROLLMENT_BATCH_INVALID), the errors list with index, code, message and params of each rejected item.

If you read only code and message, nothing needs to change.

CodeHTTPUse
INVALID_JSON400The body is not valid JSON
UNAUTHORIZED401Missing or invalid credentials
COMPANY_BLOCKED403Company blocked
PRODUCT_NOT_ACTIVE403Transaction creation without an active Prevention or Dispute (see Who sends transactions), or an enrollment request for a product your company does not have active (params.product)
VALIDATION_ERROR422One or more invalid fields
NOT_FOUND404The address does not exist in the API (typo in the path, extra trailing slash)
TRANSACTION_NOT_FOUND404Transaction does not exist
TRANSACTION_DUPLICATE409external_source + external_id already registered
TRANSACTION_IMMUTABLE409Transaction already used, cannot be updated
TRANSACTION_DELETE_NOT_ALLOWED405Transactions cannot be deleted (see Delete transaction)
MERCHANT_NOT_FOUND404Merchant does not exist
ALERT_NOT_FOUND404Alert does not exist
ALERT_INVALID_STATUS422Invalid status, or transition not allowed (deadline, expiration or status already final)
PAYLOAD_TOO_LARGE413Body above the limit: 1 MB per request, 5 MB in batch upload and in the merchant batch, 2 MB in the enrollment batch
RATE_LIMIT_EXCEEDED429Request limit exceeded (see below)
ORIGIN_NOT_ALLOWED403Capture event coming from a site that is not among the sites the token works on (see Which site the token works on)
TOO_MANY_PENDING_EVENTS429Too many capture events waiting for the transaction to show up (see Rate limit)
CAPTURE_TEMPORARILY_UNAVAILABLE503Capture temporarily unavailable. Resend the event after Retry-After, with the same event_id
SERVICE_UNAVAILABLE503Temporarily unavailable in merchants, enrollments and usage. Repeating is safe: the repeated call duplicates nothing. Wait for Retry-After
INTERNAL_ERROR500Unexpected server error

Codes of Merchants, Enrollments and Usage by merchant.

CodeHTTPUse
KYB_NOT_APPROVED403Your company’s registration has not been approved yet: writes stay blocked until approval
COMPANY_NOT_ACTIVE403The company is not active
FIELD_REQUIRED422Required field missing (params.field)
FIELD_TOO_LONG422Field above the limit (params.field, params.max)
FIELD_INVALID422Invalid value in the field (params.field)
FIELD_INVALID_OPTION422Value outside the accepted list (params.field, params.options)
BATCH_IN_PROGRESS429Another batch from your company (of the same type) is still being saved. Wait for Retry-After
MERCHANT_DUPLICATE409Another merchant of yours already has the name (params.merchant_id)
MERCHANT_REF_CONFLICT409merchant_ref differs from the saved one only in case or accents
MERCHANT_REF_TAKEN409Another merchant of yours already uses the merchant_ref
MERCHANT_REF_IMMUTABLE409The merchant_ref cannot be changed once saved
MERCHANT_HAS_HISTORY409A merchant with linked data cannot be deleted: save status: "inactive" and request the deactivation of its enrollments
MERCHANT_REF_DUPLICATE_IN_BATCH422merchant_ref repeated in the same batch
MERCHANT_NAME_DUPLICATE_IN_BATCH422name repeated in the same batch
ENROLLMENT_NOT_FOUND404Enrollment does not exist
ENROLLMENT_DUPLICATE409Identifier already in use on the platform
ENROLLMENT_PREVIOUSLY_REJECTED409Identifier rejected before; send retry_rejected: true to request it again
ENROLLMENT_DUPLICATE_IN_BATCH422Identifier repeated in the same batch
ENROLLMENT_BATCH_INVALID422All or nothing batch with a rejected item; nothing was saved (details.errors)
ENROLLMENT_NO_PRODUCT422No product requested
ENROLLMENT_PENDING_LIMIT42220,000 enrollments waiting for approval in your company
ENROLLMENT_NOTHING_TO_DEACTIVATE422No active product to deactivate
DESCRIPTOR_LOOKS_LIKE_BIN_CAID422The descriptor looks like a BIN/CAID: request it as bin_caid
DESCRIPTOR_PREFIX_TOO_SHORT422“Starts with” with fewer than 5 characters
BIN_INVALID422bin outside 6 to 10 digits
PROVIDER_UNAVAILABLE422The product does not accept this enrollment type
MERCHANT_INCOMPLETE_FOR_PREVENTION422The merchant is missing registration data for Prevention (params.fields)
USAGE_CYCLE_NOT_FOUND404No closed billing cycle starts in the requested month

All routes share a limit of 100 requests per minute per IP, including those that answer 401 for invalid credentials. The exception is the browser capture routes, which do not count toward the 100: sending an event has its own cap of 120 per minute and the snippet config of 300 per minute, both counted per IP and token. The snippet’s rapid.js script is also outside it, with its own cap of 300 per minute per IP.

When you go over it, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 15
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded, retry in 15 seconds"
}
}

Use Retry-After. It says, in seconds, how long until the window resets, and the message repeats the same number. Waiting exactly that long is better than guessing: blind exponential backoff can retry too early (and get another 429) or wait longer than needed.

Besides the 100 per IP, some routes have a per-company limit, counted by the credential:

RoutesLimit
Writes to merchants and enrollments (POST, PATCH, DELETE; each batch counts as one)60 per minute
Usage by merchant10 per minute
Merchant and enrollment batches1 of each type in progress (429 BATCH_IN_PROGRESS, Retry-After: 5)

When the per-minute limit is exceeded, the response is the same 429 RATE_LIMIT_EXCEEDED, with Retry-After.

The X-RateLimit-* headers come in every response, not only in the 429, so you can get ahead of it: when X-RateLimit-Remaining gets close to zero, hold the sending instead of waiting for the error. For volume, prefer batch upload, which sends up to 1000 transactions in one request and uses one unit of the limit.

5xx errors are usually transient. Retry with increasing intervals between attempts. When the response has Retry-After (the 503 responses do), wait that long. In merchants and enrollments, a 503 SERVICE_UNAVAILABLE may arrive after the write was saved: repeating the same call is safe, because it duplicates nothing (it comes back unchanged or existing). Do not retry other 4xx errors: they mean an error on your side and will fail again. The exception is 429: wait for the time in Retry-After and try again (see Rate limit).