Error Handling

DCE API errors use standard HTTP status codes and JSON bodies. This guide explains what to expect and how to handle failures safely.

Response patterns

Success responses are route-specific JSON objects.

Error responses commonly include:

{
  "error": "Message describing failure"
}

Some validation routes may include structured fields such as details.

Status code guide

Code	Meaning	Typical action
`200`	Success	Process response
`400`	Validation or business-rule failure	Fix request payload/parameters
`401`	Missing/invalid auth	Check API key and header
`403`	Permission denied	Verify key scope/role
`404`	Resource not found	Validate IDs/paths
`410`	Gone (e.g., consumed/expired deposit token)	Regenerate token/session
`413`	Payload too large	Reduce payload size
`429`	Rate limit reached	Retry with backoff
`500`	Internal server error	Retry later and contact support if persistent

Retry strategy

Retry only transient failures:

429, 500, network timeout/connection issues

Do not blindly retry:

400, 401, 403, most 404 (unless eventual consistency is expected)

Recommended backoff:

Exponential backoff + jitter (for example 1s, 2s, 4s, 8s with randomness)
Max attempts: 3-5 depending on operation criticality

Safe integration patterns

Treat all amount fields as decimal strings.
Use your own idempotency reference (referenceId) to prevent duplicate business actions.
Log request context (route, status, payload hash, timestamps) without logging secrets.

Example error handling (Node.js)

const response = await fetch(url, options);
const body = await response.json().catch(() => ({}));

if (!response.ok) {
  if ([429, 500].includes(response.status)) {
    // retry with backoff
  } else {
    // handle as non-retryable
    throw new Error(body.error || `HTTP ${response.status}`);
  }
}

When to contact support

Reach out with:

environment (staging or production)
endpoint + approximate timestamp (UTC)
status code + response body snippet
correlation/request ID if available

Contact: [email protected]