Skip to main content

​
Common issues

Problem: Requests fail with HTTP 401 even though credentials look correct.Things to check:
  • You’re using the right API key for the environment you’re calling (sandbox keys do not work against production, and vice versa).
  • Your JWT hasn’t expired. Tokens are short-lived — generate a new one for each request, or refresh well before expiry.
  • The Authorization header is formatted as Bearer <jwt> exactly.
  • The API key has the permissions required for the endpoint.
  • See the Authentication guide for the full JWT signing flow.
Problem: Requests are returning HTTP 429 with rate_limit_exceeded.What to do:
  • Implement exponential backoff. The rate limits page has a reference implementation.
  • Cache read responses when the data does not need to be real-time.
  • Use the largest pageSize your workload can handle when iterating — see Pagination.
  • If you consistently hit limits in production, reach out via the CDP Discord to discuss a limit increase.
Problem: A transfer was created but never reaches completed.Things to check:
  • For quoted transfers, you must call POST /v2/transfers/{transferId}/execute to commit the quote. Quotes expire if not executed in time.
  • Verify the source and target account IDs are valid and currently linked to your entity.
  • Check the transfer object for any error details on the response — failures surface there before they hit webhooks.
  • For inbound deposits requiring travel rule information, submit it via POST /v2/transfers/{transferId}/travel-rule.
Problem: A request that succeeds in sandbox returns an error against production.Things to check:
  • All credentials, account IDs, deposit destination IDs, and payment method IDs are environment-scoped. None of them carry across.
  • Switch every hardcoded sandbox value (API key, base URL, IDs) to a configuration value before promoting.
  • Production accounts may have different supported assets, networks, or KYC requirements than your sandbox setup.
  • Confirm your production API key has the permissions needed for the endpoint you’re calling.
Problem: Requests are rejected with HTTP 400.Things to check:
  • Amounts are sent as strings, not numbers. See Conventions.
  • All required fields are present and resource IDs use the right prefix (for example, account_<uuid>, not a bare UUID).
  • Optional metadata is a flat string-to-string map within the documented limits (see Metadata).
  • The full error response includes an errorLink field pointing at the specific entry in the Errors reference. Start there.
Problem: A retry returns HTTP 422 with idempotency_error.What it means: You reused an idempotency key with a different request body. The API rejects this to prevent the second request from being silently merged with the first.What to do: Generate a new UUID v4 for the retry, or send the exact original payload. See Idempotency.

​
Getting help

Discord

Ask questions and get help from the CDP community and team

Errors reference

Full catalog of error types and their meanings

Service status

Check current status of CDP services

CDP Portal

Manage API keys, accounts, and usage