Developers

API Errors & Envelope Both

Every TapTidy API error response follows a strict, predictable JSON envelope:

{
  "code": "SOME_ERROR_CODE",
  "message": "Human-readable explanation"
}

The message field always returns a sanitized, user-safe description. In compliance with security standards, the API never leaks internal exception messages, stack traces, or SQL details. Diagnostics are recorded exclusively in server-side logs.

Standard Error Codes

Code	HTTP Status	Meaning
`VALIDATION_ERROR`	400	Request payload or query parameters failed schema validation.
`UNAUTHORIZED`	401	Missing or invalid authentication credential.
`INVALID_TOKEN`	401	The provided Bearer token is expired, corrupted, or revoked.
`FORBIDDEN`	403	Valid credential, but insufficient permissions or missing scope.
`NOT_FOUND`	404	The requested resource does not exist or is not visible to this caller.
`CONFLICT`	409	The request conflicts with the current resource state (e.g. concurrency lock).
`LIMIT_REACHED`	403 / 422	Account hit an active plan limit (e.g. maximum task count or household members).
`ACCOUNT_DELETED`	403	The authenticating account has been scheduled for deletion.
`RATE_LIMIT_EXCEEDED`	429	Too many requests within the current rate window.
`INTERNAL_ERROR`	500	Unexpected server error; safe to retry with exponential backoff.

Rate Limiting Headers

Rate limits are enforced using standard IETF RateLimit-* HTTP headers (e.g. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset). Exceeding limits returns HTTP 429 with RATE_LIMIT_EXCEEDED.