Errors

The error shape

Any non-2xx response is a flat JSON object with two fields, plus an optional details:

{
  "error": "invalid email or password",
  "code": "invalid_credentials"
}

• error — a human-readable message, for logs and quick debugging. Wording can change between releases; don't parse it.
• code — a stable, snake_case identifier you can switch on. This is the contract.
• details — present on a few codes that carry structured context (see below).

Structured details

Some codes attach a details object. A unique_violation names the field that collided, so you can point the user at the right input:

{
  "error": "value violates a unique constraint",
  "code": "unique_violation",
  "details": { "field": "email" }
}

When you declare a unique constraint on a collection that already holds duplicates, the rejection carries details.duplicates — the offending value groups, so you can dedupe before retrying.

Error codes

Every code is global and stable. The defaults below apply to any endpoint based on the HTTP status; specific endpoints emit the more precise codes that follow.

Four codes are deliberately absent from these tables — error, invalid, duplicate and state_conflict. They carry nothing an application can act on, and a more specific code applies wherever one exists. Treat them as you would an unrecognised code.

Defaults

Database

Vectors & embeddings

Authentication

Storage

Platform & billing

Projects & seeding

Handling errors in the SDK

The SDKs do the code matching for you — they throw typed exceptions selected from the code, so your app catches a class instead of inspecting status or message. Data-layer failures share a base (KoolbaseDataException) you can catch broadly, or you can catch a specific subtype:

try {
  await Koolbase.db.collection('users').insert({'email': email});
} on KoolbaseConflictException catch (e) {
  // e.field is the collided field, when the server reports it
  showError('That ${e.field ?? 'value'} is already taken.');
} on KoolbasePermissionException {
  showError('You do not have permission to do that.');
} on KoolbaseDataException catch (e) {
  // Catch-all for any other data-layer error
  showError(e.message);
}

Auth methods throw KoolbaseAuthException subtypes — InvalidCredentialsException, AccountLockedException, OtpExpiredException, and so on — selected from the same codes.

Storage uploads have their own typed exception family — KoolbaseStorageConflictException, KoolbaseStorageQuotaException, KoolbaseStorageFileTooLargeException, KoolbaseStorageMimeTypeException, KoolbaseStorageNotFoundException, KoolbaseStoragePermissionException, KoolbaseStorageValidationException — all extending KoolbaseStorageException. Catch the base to handle any storage failure, or branch on the specific subclass. The upload_expired code surfaces on the base class without a dedicated subclass; check .code if you need to distinguish it.