Skip to main content

Errors & retries

Recognize the error shapes the API returns and retry the ones that are worth retrying.

Handle errors and retries#

Error shape, CLI exit codes, 429 vs 402 semantics, and Retry-After.

Errors come back as JSON with a `message` and an HTTP status. `401`/`403` mean auth (bad key or wrong project). `402` means you've hit a plan limit and need to upgrade; the call will not succeed on its own retry. `429` means rate limited — `Retry-After` (in seconds) tells you when to retry. The CLI exits non-zero with code 77 on missing API key; exit codes mirror the HTTP class for other errors.

import { DeweyClient, DeweyError } from '@meetdewey/typescript-sdk'

const client = new DeweyClient({ apiKey: process.env.DEWEY_API_KEY! })

try {
  await client.retrieval.query('COLLECTION_ID', 'who is the cfo?')
} catch (err) {
  if (err instanceof DeweyError) {
    if (err.status === 429) {
      const retryAfter = Number((err as any).headers?.['retry-after'] ?? 5)
      console.warn(`Rate limited. Retrying in ${retryAfter}s...`)
      await new Promise((r) => setTimeout(r, retryAfter * 1000))
    } else if (err.status === 402) {
      console.error('Plan limit reached:', err.message)
      // Direct the user to upgrade — retrying won't help.
    } else if (err.status >= 500) {
      console.error('Transient server error, safe to retry.')
    } else {
      console.error('Client error:', err.status, err.message)
    }
  } else {
    throw err
  }
}

Response

{
  "error": {
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "status": 429,
    "code": "rate_limited",
    "retryAfter": 12
  }
}

See also