Common problems
Found your symptom? The likely cause is in one line, and the detail is on the linked page.
Credentials and access
Section titled “Credentials and access”Every call returns 401
Section titled “Every call returns 401”The Authorization header does not match: wrong credentials, a secret from before a rotation in the dashboard (it only works for 24 hours, or until it is revoked), or base64 built over something other than client_id:client_secret. See Authentication.
The API returns 403 COMPANY_BLOCKED
Section titled “The API returns 403 COMPANY_BLOCKED”The company is blocked at Rapid. Credential-based calls stop; webhooks keep arriving. See Blocked companies.
I get 429
Section titled “I get 429”You went over the request limit. Wait the time in the Retry-After header and, for volume, use batch upload. See Rate limit.
I get 404 NOT_FOUND on an endpoint that exists
Section titled “I get 404 NOT_FOUND on an endpoint that exists”The path differs: an extra trailing slash, missing /api/v1 or a typo. See Response codes.
Webhook
Section titled “Webhook”No webhook arrives
Section titled “No webhook arrives”First check that the webhook is registered and active under Settings › Webhook: without that there is no delivery and nothing in the log. Then check the reason for each attempt in the dashboard’s delivery log, under Activity, Webhooks tab: it starts with [https], [destino], [redirecionamento] or [assinatura] when the failure was not a response from your server. See Retries and logs.
The signature never matches
Section titled “The signature never matches”Almost always the body was parsed as JSON before validating: the signature covers the raw body, byte for byte. Other causes: a key that was already rotated, and a timestamp outside the window. Test it with the signature checker and compare with the examples in Webhook authentication.
The log shows a failure, but my server received it
Section titled “The log shows a failure, but my server received it”Your server answered outside 2xx or took longer than the time limit. See What counts as success.
The same alert arrived twice
Section titled “The same alert arrived twice”It is a retry or a redelivery, with the same alert_id. See Idempotency.
Alerts
Section titled “Alerts”422 ALERT_INVALID_STATUS when responding to an alert
Section titled “422 ALERT_INVALID_STATUS when responding to an alert”The deadline passed or the alert already has a final status. The message says which case it is. See Transition not allowed.
I do not know the alert id, only the provider’s
Section titled “I do not know the alert id, only the provider’s”Search by provider_alert_id. See Search by your own ID.
Transactions
Section titled “Transactions”403 PRODUCT_NOT_ACTIVE when sending a transaction
Section titled “403 PRODUCT_NOT_ACTIVE when sending a transaction”The company has neither Prevention nor Dispute active, and only they use transactions. Subscribe to or activate one of them in the dashboard, or contact support. See Who sends transactions.
409 TRANSACTION_DUPLICATE
Section titled “409 TRANSACTION_DUPLICATE”You already have a transaction with the same external_source and external_id. See Error codes.
409 TRANSACTION_IMMUTABLE
Section titled “409 TRANSACTION_IMMUTABLE”The transaction was already used by a product and can no longer be changed. See Immutability protection.
404 MERCHANT_NOT_FOUND
Section titled “404 MERCHANT_NOT_FOUND”The merchant_id is not one of your company’s merchants. See List merchants.
I lost the transaction id
Section titled “I lost the transaction id”Find it by the identifier you sent. See By your system’s ID.
413 PAYLOAD_TOO_LARGE in batch upload
Section titled “413 PAYLOAD_TOO_LARGE in batch upload”The body went over the maximum size. Split it into smaller batches. See Batch upload.
The response has warnings
Section titled “The response has warnings”The transaction was created, but fields that improve protection are missing. See Warnings.
A dispute arrived without the associated transaction
Section titled “A dispute arrived without the associated transaction”The transaction does not have the charge identifier in the gateway. See Note on transaction_id.
Capture
Section titled “Capture”Browser events return 403 ORIGIN_NOT_ALLOWED
Section titled “Browser events return 403 ORIGIN_NOT_ALLOWED”The event came from a site that is not among the sites the token works on. If the site is yours, authorize it on the SDK card, under Settings › Integrations. See Which site the token works on.
The SDK card does not show “capturing”
Section titled “The SDK card does not show “capturing””The card changes when an event matches one of your transactions. Check that the transaction was sent and that order_ref is its identifier. See order_ref.
I get 429 TOO_MANY_PENDING_EVENTS
Section titled “I get 429 TOO_MANY_PENDING_EVENTS”Too many events are waiting for the transaction to show up. Usually order_ref matches no transaction, or the transactions are not being sent. The browser and the server have separate ceilings. In the browser, it can also be someone sending made-up orders with your token: generate a new one on the SDK card to cut off new sends; the ones already in leave the queue on their own in about 3 days. See Rate limit.
I get 503 CAPTURE_TEMPORARILY_UNAVAILABLE
Section titled “I get 503 CAPTURE_TEMPORARILY_UNAVAILABLE”Capture intake was unavailable for a moment and the event was not recorded. Resend it after the number of seconds in the Retry-After header, with the same event_id: the resend does not duplicate the evidence. See Validations.