Skip to main content
The TaxHomeBase API uses standard HTTP status codes and returns JSON error responses.

​
Error Response Format

All errors return a JSON object with an error field: 
{
  "error": "Descriptive error message"
}
Some endpoints return additional fields for bulk operations: 
{
  "imported": 45,
  "skipped": 3,
  "errors": [
    { "row": 12, "reason": "Invalid date '2024-13-01'" },
    { "row": 28, "reason": "Missing required field: amount" }
  ]
}

​
Status Codes

​
Success Codes

CodeMeaningUsed For
200OKSuccessful reads, updates, deletes
201CreatedSuccessful resource creation

​
Client Error Codes

CodeMeaningCommon Causes
400Bad RequestValidation failure, missing required fields, invalid values
401UnauthorizedMissing or expired JWT token
403ForbiddenWrong plan, disabled account, accessing another user’s data
404Not FoundResource doesn’t exist or belongs to another user
409ConflictUnique constraint violation (e.g., duplicate quarterly payment for same quarter)
422Unprocessable EntityProcessing failure (e.g., Textract can’t read receipt, Claude can’t parse contract)

​
Server Error Codes

CodeMeaningCommon Causes
500Internal Server ErrorUnexpected server error (logged with request ID)
503Service UnavailableExternal service not configured (e.g., Stripe, Anthropic API)

​
Validation Errors

The API validates inputs and returns 400 with a descriptive message: 
{
  "error": "Valid state code is required"
}

{
  "error": "base_pay must be a non-negative integer (cents)"
}

{
  "error": "Invalid status transition from complete to active"
}

​
Common Validation Rules

RuleDescription
Money valuesNon-negative integers representing cents
DatesISO format (YYYY-MM-DD)
Years4-digit YYYY (1990–2100)
MonthsInteger 1–12
State codes2-letter uppercase (AL, AK, … WY)
String lengthsEnforced per field (e.g., facility 255, notes 1000)
File uploads1–10MB, specific content types (PDF, JPEG, PNG)
EnumsStrict validation against allowed values

​
Request IDs

Every response includes an X-Request-Id header. Include this ID when reporting errors — it correlates with server-side logs for debugging. 
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000