DramWell Docs

Overview

When a request cannot be completed, the DramWell API returns a structured error object alongside an appropriate HTTP status code. Every error follows the same shape so you can write a single error-handling path regardless of which endpoint failed.

Error Response Format

{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "The 'customer_id' field is required.",
    "param": "customer_id",
    "doc_url": "https://docs.dramwell.ai/api/errors#missing_required_field"
  }
}

Field	Type	Description
`type`	string	The broad error category — see types below
`code`	string	A machine-readable code for the specific error
`message`	string	A human-readable description of what went wrong
`param`	string or null	The request field that caused the error, when applicable
`doc_url`	string	A direct link to the relevant documentation

Error Types

Type	HTTP Status	Description
`validation_error`	400	The request body or query parameters failed validation
`authentication_error`	401	Missing, invalid, or expired credentials
`authorization_error`	403	Valid credentials but insufficient permissions
`not_found`	404	The requested resource does not exist
`conflict`	409	The action would create a duplicate or violate a constraint
`rate_limit_error`	429	Too many requests — see Rate Limits
`server_error`	500	An unexpected error occurred on our side

HTTP Status Codes

400 Bad Request

The request is malformed or missing required fields. Check the param field to identify which input caused the issue.

401 Unauthorized

No credentials were supplied, or the credentials are invalid or expired. Verify your Authorization header is present and that your API key or JWT has not been revoked.

403 Forbidden

Your credentials are valid but your account or role does not have permission to perform this action. Contact your organization owner to review your permissions.

404 Not Found

The resource with the specified ID does not exist, or it belongs to a different organization. Verify the ID and that your API key is scoped to the correct organization.

429 Too Many Requests

You have exceeded your rate limit. Read the X-RateLimit-Reset header and wait until that timestamp before retrying. See Rate Limits for details.

500 Internal Server Error

An unexpected error occurred on our servers. These are automatically reported to our engineering team. If the issue persists, contact support@dramwell.ai with the request ID from the response headers (X-Request-Id).

Retry Logic

We recommend the following retry strategy:

Do not retry 400, 401, 403, or 404 — these indicate a problem with your request that will not resolve on its own.
Retry with backoff on 429 and 5xx responses.
Use exponential backoff starting at 1 second, doubling up to a maximum of 32 seconds.
Add jitter (random ±20%) to avoid thundering-herd problems when many clients retry simultaneously.

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options)
    if (response.ok) return response

    const { status } = response
    if (status < 500 && status !== 429) throw new Error(`Non-retryable error: ${status}`)
    if (attempt === maxRetries) throw new Error(`Max retries exceeded`)

    const delay = Math.min(1000 * 2 ** attempt * (0.8 + Math.random() * 0.4), 32000)
    await new Promise(resolve => setTimeout(resolve, delay))
  }
}

Error Handling