Error Codes

All API errors return a consistent JSON structure. This page documents every error type, its HTTP status code, and the response body format.

Response Format

Every error response follows this structure:

{
  "error": "ErrorCode",
  "message": "Human-readable description",
  "path": "affected.field.path",
  "suggestion": "How to fix this",
  "details": {}
}

Field	Type	Always present	Description
error	string	Yes	Machine-readable error code
message	string	Yes	Human-readable description of what went wrong
path	string	No	Dot-delimited path to the affected field (e.g. field_values.priority)
suggestion	string	No	Actionable fix for the error
details	object	No	Additional structured information (varies by error type)

---

Error Types

Error	HTTP Status	Description
ThogitNotFound	404	Thogit ID does not exist
TagNotFound	404	Tag ID does not exist
TagAlreadyApplied	409	Tag is already applied to this thogit
DuplicateTagName	409	Another tag already has this name
TagInUse	400	Cannot delete tag that is applied to thogits
MissingField	400	Required field not provided
ValidationErrors	400	Field values don’t match schema
FilterError	400	Invalid filter syntax or unknown tag/field
SchemaError	400	Invalid schema definition
InvalidReference	400	Reference points to non-existent thogit
DatabaseError	500	Internal database error

---

Error Details

ThogitNotFound

Returned when a thogit ID is referenced but does not exist in the database.

{
  "error": "ThogitNotFound",
  "message": "Thogit not found: 01JQXK6V9XCSV5K9Z1MQSK5RBT"
}

TagNotFound

Returned when a tag ID is referenced but does not exist or has been soft-deleted.

{
  "error": "TagNotFound",
  "message": "Tag not found: 01JR2M8K3XNWV7P4Q6YT0HABCD"
}

TagAlreadyApplied

Returned when attempting to apply a tag that is already on the thogit.

{
  "error": "TagAlreadyApplied",
  "message": "Tag 'Project Tracker' is already applied to this thogit",
  "suggestion": "Remove the tag first if you want to re-apply it with different values"
}

DuplicateTagName

Returned when creating or renaming a tag would conflict with an existing tag name.

{
  "error": "DuplicateTagName",
  "message": "A tag named 'Project Tracker' already exists",
  "suggestion": "Choose a different name"
}

TagInUse

Returned when attempting to delete a tag that is still applied to one or more thogits.

{
  "error": "TagInUse",
  "message": "Cannot delete tag 'Project Tracker': applied to 12 thogits",
  "suggestion": "Remove the tag from all thogits before deleting"
}

MissingField

Returned when a required request field is not provided.

{
  "error": "MissingField",
  "message": "Field 'name' is required",
  "path": "name"
}

ValidationErrors

Returned when field values do not match the tag schema. The details object contains per-field validation errors.

{
  "error": "ValidationErrors",
  "message": "2 field validation errors",
  "details": {
    "errors": [
      {
        "path": "priority",
        "expected_type": "Number",
        "actual_type": "String",
        "suggestion": "Use a numeric value like 42"
      },
      {
        "path": "due_date",
        "expected_type": "Date",
        "actual_type": "String",
        "suggestion": "Use YYYY-MM-DD format like \"2024-01-15\""
      }
    ]
  }
}

ValidationError detail structure

Each entry in the errors array has:

Field	Type	Description
path	string	Field name that failed validation
expected_type	string	The schema type the field expects
actual_type	string	The JSON type of the value that was provided
suggestion	string	How to fix the value

FilterError

Returned when a filter is syntactically invalid or references unknown tags/fields.

{
  "error": "FilterError",
  "message": "Unknown tag 'Projct' in filter 'Projct.status'",
  "suggestion": "Did you mean 'Project'?"
}

SchemaError

Returned when a tag schema definition is invalid.

{
  "error": "SchemaError",
  "message": "Invalid field type 'Text' in schema",
  "path": "schema.title",
  "suggestion": "Valid types are: String, Number, Boolean, Date, Reference, Select, MultiSelect"
}

InvalidReference

Returned when a Reference field value points to a thogit that does not exist.

{
  "error": "InvalidReference",
  "message": "Reference field 'parent' points to non-existent thogit: 01JQXK6V9XCSV5K9Z1MQSK5RBT",
  "path": "field_values.parent"
}

DatabaseError

Returned on unexpected internal failures. The message is generic to avoid leaking implementation details.

{
  "error": "DatabaseError",
  "message": "Internal server error"
}

Caution

DatabaseError responses intentionally omit internal details for security. If you encounter this error persistently, contact support.

---

HTTP Status Codes Summary

Code	Meaning	When it occurs
200	Success	Successful GET, PUT, PATCH, DELETE
302	Redirect	OAuth authentication flows
400	Bad Request	Validation errors, schema errors, filter errors, tag in use, invalid reference
401	Unauthorized	No session cookie, or 2FA pending
404	Not Found	Thogit or tag ID does not exist
409	Conflict	Duplicate tag name, tag already applied
500	Internal Server Error	Database failures, unexpected panics

---

Handling Errors

TypeScript

import { client } from 'thogits-client';

try {
  const thogit = await client.getThogit({ id });
} catch (err) {
  if (err.status === 404) {
    console.log('Thogit not found');
  } else if (err.status === 400 && err.body?.error === 'ValidationErrors') {
    for (const detail of err.body.details.errors) {
      console.log(`${detail.path}: expected ${detail.expected_type}, got ${detail.actual_type}`);
      console.log(`  Fix: ${detail.suggestion}`);
    }
  }
}

curl

# Errors are returned as JSON with the appropriate HTTP status code
curl -s -w "\nHTTP %{http_code}\n" \
  https://app.thogits.com/api/thogits/invalid-id

# Response:
# {"error":"ThogitNotFound","message":"Thogit not found: invalid-id"}
# HTTP 404