Error Reference - Dark Obsidian API Docs

Error format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "docs": "https://darkobsedian.sameergul.com/docs/errors#VALIDATION_ERROR"
  }
}

Error codes

Code	HTTP	Description	Fix
UNAUTHORIZED	401	Missing or invalid API key	Include `Authorization: Bearer do_live_...` header
FORBIDDEN	403	API key lacks permission for this resource	Regenerate key with required permissions in Settings → Developer
NOT_FOUND	404	Resource or endpoint not found	Check the ID or URL path
VALIDATION_ERROR	400	Missing or invalid request parameters	Read the message field for details
RATE_LIMITED	429	Daily request limit reached	Limit resets at midnight UTC. Upgrade plan for higher limits.
IDEMPOTENCY_CONFLICT	409	Duplicate request with same idempotency key but different body	Use a unique `X-Idempotency-Key` for each distinct request. See the Idempotency guide.
SERVER_ERROR	500	Internal server error	Retry with exponential backoff. Contact support if persistent.

Handling errors (JavaScript)

import { DarkObsidianError } from './dark-obsidian'

try {
  const order = await client.orders.create({ items: [] })
} catch (err) {
  if (err instanceof DarkObsidianError) {
    switch (err.code) {
      case 'VALIDATION_ERROR':
        console.error('Fix your request:', err.message)
        break
      case 'RATE_LIMITED':
        console.error('Slow down - limit resets at midnight UTC')
        break
      case 'UNAUTHORIZED':
        console.error('Check your API key')
        break
      default:
        console.error(`API error: ${err.code} - ${err.message}`)
    }
  }
}

Handling errors (Python)

from dark_obsidian import DarkObsidian, DarkObsidianError

try:
    order = client.orders.create(items=[])
except DarkObsidianError as e:
    if e.code == 'VALIDATION_ERROR':
        print(f"Fix your request: {e.message}")
    elif e.code == 'RATE_LIMITED':
        print("Rate limited - try again tomorrow")
    else:
        print(f"Error {e.status}: {e.message}")