Response codes
Reference of the HTTP codes used across the whole Rapid API.
Success codes
Section titled “Success codes”| Code | Meaning |
|---|---|
| 200 | Success with body |
| 201 | Resource created |
| 204 | Success with no body (e.g. Delete merchant) |
Client error codes
Section titled “Client error codes”| Code | Meaning |
|---|---|
| 400 | Body is not valid JSON (INVALID_JSON) |
| 401 | Missing or invalid credentials |
| 403 | Company blocked, company registration not approved yet (KYB_NOT_APPROVED), or required product not active (PRODUCT_NOT_ACTIVE) |
| 404 | Resource not found |
| 405 | Operation not allowed (TRANSACTION_DELETE_NOT_ALLOWED) |
| 409 | Conflict (duplicate, update of an immutable resource) |
| 413 | Body above the maximum size (PAYLOAD_TOO_LARGE) |
| 422 | Validation error |
| 429 | Too many requests (rate limit) |
Server error codes
Section titled “Server error codes”| Code | Meaning |
|---|---|
| 500 | Internal error (INTERNAL_ERROR), retry recommended |
| 503 | Temporarily unavailable (SERVICE_UNAVAILABLE, CAPTURE_TEMPORARILY_UNAVAILABLE), with Retry-After |
Error body format
Section titled “Error body format”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), theerrorslist withindex,code,messageandparamsof each rejected item.
If you read only code and message, nothing needs to change.
Most common semantic codes
Section titled “Most common semantic codes”| Code | HTTP | Use |
|---|---|---|
INVALID_JSON | 400 | The body is not valid JSON |
UNAUTHORIZED | 401 | Missing or invalid credentials |
COMPANY_BLOCKED | 403 | Company blocked |
PRODUCT_NOT_ACTIVE | 403 | Transaction 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_ERROR | 422 | One or more invalid fields |
NOT_FOUND | 404 | The address does not exist in the API (typo in the path, extra trailing slash) |
TRANSACTION_NOT_FOUND | 404 | Transaction does not exist |
TRANSACTION_DUPLICATE | 409 | external_source + external_id already registered |
TRANSACTION_IMMUTABLE | 409 | Transaction already used, cannot be updated |
TRANSACTION_DELETE_NOT_ALLOWED | 405 | Transactions cannot be deleted (see Delete transaction) |
MERCHANT_NOT_FOUND | 404 | Merchant does not exist |
ALERT_NOT_FOUND | 404 | Alert does not exist |
ALERT_INVALID_STATUS | 422 | Invalid status, or transition not allowed (deadline, expiration or status already final) |
PAYLOAD_TOO_LARGE | 413 | Body 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_EXCEEDED | 429 | Request limit exceeded (see below) |
ORIGIN_NOT_ALLOWED | 403 | Capture 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_EVENTS | 429 | Too many capture events waiting for the transaction to show up (see Rate limit) |
CAPTURE_TEMPORARILY_UNAVAILABLE | 503 | Capture temporarily unavailable. Resend the event after Retry-After, with the same event_id |
SERVICE_UNAVAILABLE | 503 | Temporarily unavailable in merchants, enrollments and usage. Repeating is safe: the repeated call duplicates nothing. Wait for Retry-After |
INTERNAL_ERROR | 500 | Unexpected server error |
Merchants, enrollments and usage
Section titled “Merchants, enrollments and usage”Codes of Merchants, Enrollments and Usage by merchant.
| Code | HTTP | Use |
|---|---|---|
KYB_NOT_APPROVED | 403 | Your company’s registration has not been approved yet: writes stay blocked until approval |
COMPANY_NOT_ACTIVE | 403 | The company is not active |
FIELD_REQUIRED | 422 | Required field missing (params.field) |
FIELD_TOO_LONG | 422 | Field above the limit (params.field, params.max) |
FIELD_INVALID | 422 | Invalid value in the field (params.field) |
FIELD_INVALID_OPTION | 422 | Value outside the accepted list (params.field, params.options) |
BATCH_IN_PROGRESS | 429 | Another batch from your company (of the same type) is still being saved. Wait for Retry-After |
MERCHANT_DUPLICATE | 409 | Another merchant of yours already has the name (params.merchant_id) |
MERCHANT_REF_CONFLICT | 409 | merchant_ref differs from the saved one only in case or accents |
MERCHANT_REF_TAKEN | 409 | Another merchant of yours already uses the merchant_ref |
MERCHANT_REF_IMMUTABLE | 409 | The merchant_ref cannot be changed once saved |
MERCHANT_HAS_HISTORY | 409 | A merchant with linked data cannot be deleted: save status: "inactive" and request the deactivation of its enrollments |
MERCHANT_REF_DUPLICATE_IN_BATCH | 422 | merchant_ref repeated in the same batch |
MERCHANT_NAME_DUPLICATE_IN_BATCH | 422 | name repeated in the same batch |
ENROLLMENT_NOT_FOUND | 404 | Enrollment does not exist |
ENROLLMENT_DUPLICATE | 409 | Identifier already in use on the platform |
ENROLLMENT_PREVIOUSLY_REJECTED | 409 | Identifier rejected before; send retry_rejected: true to request it again |
ENROLLMENT_DUPLICATE_IN_BATCH | 422 | Identifier repeated in the same batch |
ENROLLMENT_BATCH_INVALID | 422 | All or nothing batch with a rejected item; nothing was saved (details.errors) |
ENROLLMENT_NO_PRODUCT | 422 | No product requested |
ENROLLMENT_PENDING_LIMIT | 422 | 20,000 enrollments waiting for approval in your company |
ENROLLMENT_NOTHING_TO_DEACTIVATE | 422 | No active product to deactivate |
DESCRIPTOR_LOOKS_LIKE_BIN_CAID | 422 | The descriptor looks like a BIN/CAID: request it as bin_caid |
DESCRIPTOR_PREFIX_TOO_SHORT | 422 | “Starts with” with fewer than 5 characters |
BIN_INVALID | 422 | bin outside 6 to 10 digits |
PROVIDER_UNAVAILABLE | 422 | The product does not accept this enrollment type |
MERCHANT_INCOMPLETE_FOR_PREVENTION | 422 | The merchant is missing registration data for Prevention (params.fields) |
USAGE_CYCLE_NOT_FOUND | 404 | No closed billing cycle starts in the requested month |
Rate limit
Section titled “Rate limit”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 RequestsRetry-After: 15X-RateLimit-Limit: 100X-RateLimit-Remaining: 0X-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.
Per-company limits
Section titled “Per-company limits”Besides the 100 per IP, some routes have a per-company limit, counted by the credential:
| Routes | Limit |
|---|---|
Writes to merchants and enrollments (POST, PATCH, DELETE; each batch counts as one) | 60 per minute |
| Usage by merchant | 10 per minute |
| Merchant and enrollment batches | 1 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.
Retrying 5xx errors
Section titled “Retrying 5xx errors”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).