Errors and retries

Errors

Every API error arrives as a DocondaError:

import { DocondaError } from "@doconda/sdk"

try {
  await doconda.documents.create({ format: "docx", prompt: "Memo for the team" })
} catch (e) {
  if (!(e instanceof DocondaError)) throw e
  console.log(e.status)    // 402
  console.log(e.code)      // "insufficient_balance": stable, use it to decide
  console.log(e.message)   // explanation in English, for your logs
  console.log(e.errors)    // on 422: which field is wrong and why
  console.log(e.requestId) // give it to us if you contact support
}

The ones you will see most:

`code`	What to do
`input_invalid`	Fix the request: `e.errors` tells you which field.
`insufficient_balance`	Top up your balance in the dashboard (or turn on auto top-up).
`unauthorized`	The key does not exist or has been revoked.
`region_mismatch`	The key belongs to another region: don’t change `baseUrl`, the SDK already picks the right one.
`not_found`	That document does not belong to this project.

The full list is in errors. A document that fails during processing is not an exception: create returns it with status: "failed" and doc.error. There is no charge.

Retries

The SDK only retries network failures, 429 and 5xx, waiting a little longer each time (or as long as the API says). Errors in your request (4xx) are not retried: repeating them would give the same result.

Never the same document twice

Every creation carries an Idempotency-Key: if a retry arrives after the first attempt actually succeeded, the API returns the same document instead of creating (and charging for) another one. If your program can repeat the operation on its own (a job that retries, a user who clicks twice), pass your own key, stable for that operation:

await doconda.documents.create({ format: "docx", prompt: "…" }, { idempotencyKey: `welcome-letter-${userId}` })

The API remembers it for 24 hours.

Get started

Guides

Reference

Errors and retries

Errors

Retries

Never the same document twice

​Errors

​Retries

​Never the same document twice

Errors

Retries

Never the same document twice