Error Reference

Every error code returned by the API, with its cause and solution.

Error Format

{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "Document 'abc123' not found",
    "status": 404,
    "details": {}
  }
}

UNAUTHORIZED401

Cause: Missing or invalid API key

Solution: Check your Authorization header. Keys must start with 'jdb_sk_'.

FORBIDDEN403

Cause: Key doesn't have permission for this operation

Solution: Use a read-write key for write operations, or check namespace access.

DOCUMENT_NOT_FOUND404

Cause: The requested document does not exist

Solution: Verify the document ID and namespace.

COLLECTION_NOT_FOUND404

Cause: The namespace does not exist

Solution: Create the namespace first in the dashboard settings.

CONFLICT409

Cause: A document with this ID already exists

Solution: Use a different ID, or use PUT to replace the existing document.

VALIDATION_FAILED400

Cause: Document does not match the collection schema

Solution: Check the errors array for field-specific validation failures.

INVALID_JSON400

Cause: Request body is not valid JSON

Solution: Ensure Content-Type is application/json and the body is valid JSON.

INVALID_PATCH400

Cause: Invalid JSON Patch operation

Solution: Check patch operations conform to RFC 6902 (add, replace, remove, test).

INVALID_SCHEMA400

Cause: The provided JSON Schema is invalid

Solution: Ensure the schema has a 'type' property and is valid JSON Schema.

DOCUMENT_TOO_LARGE413

Cause: Document exceeds size limit

Solution: Free: 16KB max, Pro: 1MB max. Reduce document size.

SCHEMA_TOO_LARGE413

Cause: Schema exceeds 64KB limit

Solution: Simplify the schema or remove unnecessary definitions.

QUOTA_EXCEEDED429

Cause: Document or namespace limit reached

Solution: Upgrade to Pro for higher limits, or delete unused documents.

RATE_LIMITED429

Cause: Too many requests per second

Solution: Free: 10 req/s, Pro: 100 req/s. Add retry with exponential backoff.

BULK_LIMIT_EXCEEDED400

Cause: Too many operations in a bulk request

Solution: Free: 25 max, Pro: 100 max. Split into multiple requests.

INTERNAL_ERROR500

Cause: Unexpected server error

Solution: Retry the request. If persistent, contact support.