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, credentials regenerated in the dashboard (the previous ones stop working immediately), 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”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 or deleted. 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.