Error Reference

Every API error follows the same response envelope:

{
  "data": null,
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE"
  }
}

The code field is a stable, machine-readable identifier. The message field may change and should not be parsed programmatically.

UNAUTHORIZED

HTTP Status: 401 Unauthorized

The request has no valid credentials. Either the Authorization header is missing, the API key is invalid, or the session has expired.

Common causes:

No Authorization header provided
API key is malformed (must match nb_sk_ + 32 hex characters)
API key has been deleted or revoked
Session cookie has expired

Example response:

{
  "data": null,
  "error": {
    "message": "Unauthorized",
    "code": "UNAUTHORIZED"
  }
}

How to fix:

Verify your API key starts with nb_sk_ and is 38 characters total
Check that the key hasn’t been deleted in Settings → API Keys
Use GET /api/keys to confirm the key prefix matches an active key
If using session auth, sign in again at notebind.com

FORBIDDEN

HTTP Status: 403 Forbidden

You are authenticated but lack permission for the requested action.

Common causes:

Trying to accept/reject a suggestion on a document you don’t own
Editing a comment body that was authored by someone else
Share token with insufficient permission (e.g., view token used to create a comment)
Missing Content-Type: application/json header (triggers SvelteKit CSRF protection)

Example response:

{
  "data": null,
  "error": {
    "message": "Only the document owner can accept or reject suggestions",
    "code": "FORBIDDEN"
  }
}

How to fix:

Check the permissions table in the relevant endpoint docs
Ensure you’re the document owner for owner-only actions
For share token access, verify the token has the required permission level
Always include Content-Type: application/json on requests with a body

NOT_FOUND

HTTP Status: 404 Not Found

The requested resource does not exist or you don’t have access to it.

Common causes:

Invalid or mistyped UUID in the URL path
Document, comment, or suggestion has been deleted
Trying to access a document you don’t own (without a share token)
API key ID doesn’t match any of your keys

Example response:

{
  "data": null,
  "error": {
    "message": "Document not found",
    "code": "NOT_FOUND"
  }
}

How to fix:

Double-check the resource ID in your request URL
Use the list endpoint to confirm the resource still exists
Verify you own the document, or include a valid share_token query parameter

VALIDATION_ERROR

HTTP Status: 400 Bad Request

The request body is missing required fields, contains invalid values, or is not valid JSON.

Common causes:

Missing body field when creating a comment
Missing original_text or suggested_text when creating a suggestion
Document title exceeds 500 characters
API key name exceeds 100 characters or is empty
Request body is not valid JSON
PATCH request with no recognized fields

Example response:

{
  "data": null,
  "error": {
    "message": "Missing required field: body",
    "code": "VALIDATION_ERROR"
  }
}

How to fix:

Check the request body against the required fields in the endpoint docs
Ensure your JSON is well-formed (use JSON.stringify() or json.dumps() rather than string concatenation)
Verify string fields don’t exceed their maximum length

ALREADY_RESOLVED

HTTP Status: 400 Bad Request

The suggestion has already been accepted or rejected and cannot be resolved again.

Common causes:

Accepting a suggestion that was already accepted
Rejecting a suggestion that was already rejected or accepted
Race condition when multiple clients resolve the same suggestion

Example response:

{
  "data": null,
  "error": {
    "message": "Suggestion has already been resolved",
    "code": "ALREADY_RESOLVED"
  }
}

How to fix:

Check the suggestion’s status field before attempting to resolve it
Filter your list by status: "pending" to only show actionable suggestions
Handle this error gracefully — the desired outcome (resolved suggestion) was already achieved

TEXT_NOT_FOUND

HTTP Status: 409 Conflict

When accepting a suggestion, the original_text could not be found in the current document content. The document was likely edited after the suggestion was created.

Common causes:

Another user or agent edited the document, changing or removing the suggested text
A different suggestion was accepted first that modified the same text region
The document content was replaced entirely

Example response:

{
  "data": null,
  "error": {
    "message": "Original text no longer found in document. The document may have been edited since this suggestion was created.",
    "code": "TEXT_NOT_FOUND"
  }
}

How to fix:

Fetch the current document content and compare with the suggestion’s original_text
Reject the stale suggestion and create a new one based on the current content
Consider pulling the latest document content before processing suggestions

DB_ERROR

HTTP Status: 500 Internal Server Error

An unexpected database error occurred. These are rare and typically transient.

Common causes:

Temporary database connectivity issues
Internal constraint violations

Example response:

{
  "data": null,
  "error": {
    "message": "Database error",
    "code": "DB_ERROR"
  }
}

How to fix:

Retry the request after a short delay
If the error persists, check the Notebind status page or contact support

Troubleshooting

Getting 403 on every request

The most common cause is a missing Content-Type: application/json header. SvelteKit’s CSRF protection rejects requests without it, returning 403 Forbidden — even if your credentials are correct.

# Wrong — will return 403
curl -X POST https://notebind.com/api/documents \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -d '{"title": "Test"}'

# Correct
curl -X POST https://notebind.com/api/documents \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test"}'

API key suddenly returns 401

API keys can be deleted from the web UI or via DELETE /api/keys/:id. Check your active keys:

curl https://notebind.com/api/keys \
  -H "Authorization: Bearer nb_sk_ANOTHER_WORKING_KEY"

If the key’s prefix no longer appears in the list, it was deleted. Create a new one in Settings → API Keys.

Wrong Content-Type on non-JSON requests

GET and DELETE requests don’t need a body or Content-Type header. Only include it on POST and PATCH requests:

# GET — no Content-Type needed
curl https://notebind.com/api/documents \
  -H "Authorization: Bearer nb_sk_YOUR_KEY"

# POST — Content-Type required
curl -X POST https://notebind.com/api/documents \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Doc"}'