Error Codes

The DirectCryptoPay API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes#

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body, missing required fields, or invalid parameters
`401`	Unauthorized	Missing, invalid, expired, or revoked API key
`403`	Forbidden	Valid API key but insufficient scopes for this endpoint
`404`	Not Found	The requested resource does not exist or does not belong to your tenant
`429`	Too Many Requests	Rate limit exceeded (60 requests/minute)
`500`	Internal Server Error	Unexpected server error -- contact support if persistent

Error Response Format#

All error responses include a JSON body with details:

{
  "statusCode": 401,
  "message": "Invalid, expired, or revoked API key",
  "error": "Unauthorized"
}

Scope Errors#

When a key lacks the required scope:

{
  "statusCode": 403,
  "message": "Insufficient scope. Required: [payments:write]",
  "error": "Forbidden"
}

Validation Errors#

When request parameters are invalid:

{
  "statusCode": 400,
  "message": "Integration not found or inactive",
  "error": "Bad Request"
}

Rate Limiting#

When rate-limited, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Wait the number of seconds indicated before retrying.

Troubleshooting#

Error	Likely Cause	Fix
`401` Unauthorized	Wrong key type or expired key	Check key prefix (`dcp_pk_`) and expiration
`403` Forbidden	Missing scope	Check key scopes in Dashboard > API Keys
`404` Not Found	Wrong resource ID or cross-tenant access	Verify the ID belongs to your account
`429` Rate Limited	Too many requests	Implement backoff/retry logic

Previous Endpoints Next Pricing