> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues integrating with the CDP API and how to resolve them.

## Common issues

<AccordionGroup>
  <Accordion title="401 Unauthorized errors">
    **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](/api-reference/v2/authentication) for the full JWT signing flow.
  </Accordion>

  <Accordion title="Hitting rate limits">
    **Problem:** Requests are returning HTTP 429 with `rate_limit_exceeded`.

    **What to do:**

    * Implement exponential backoff. The [rate limits page](/api-reference/v2/rate-limits) 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](/api-reference/v2/pagination).
    * If you consistently hit limits in production, reach out via the [CDP Discord](https://discord.com/invite/cdp) to discuss a limit increase.
  </Accordion>

  <Accordion title="Transfers stuck in `pending` or `processing`">
    **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`.
  </Accordion>

  <Accordion title="Code works in sandbox but fails in production">
    **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.
  </Accordion>

  <Accordion title="400 Bad Request / invalid request errors">
    **Problem:** Requests are rejected with HTTP 400.

    **Things to check:**

    * Amounts are sent as **strings**, not numbers. See [Conventions](/api-reference/v2/conventions#amounts).
    * 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](/payments/metadata)).
    * The full error response includes an `errorLink` field pointing at the specific entry in the [Errors](/api-reference/v2/errors) reference. Start there.
  </Accordion>

  <Accordion title="Idempotency key conflicts (422)">
    **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](/api-reference/v2/idempotency).
  </Accordion>
</AccordionGroup>

## Getting help

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.com/invite/cdp">
    Ask questions and get help from the CDP community and team
  </Card>

  <Card title="Errors reference" icon="triangle-exclamation" href="/api-reference/v2/errors">
    Full catalog of error types and their meanings
  </Card>

  <Card title="Service status" icon="signal" href="/get-started/support/status">
    Check current status of CDP services
  </Card>

  <Card title="CDP Portal" icon="browser" href="https://portal.cdp.coinbase.com">
    Manage API keys, accounts, and usage
  </Card>
</CardGroup>