Error Handling

The Templated API uses standard HTTP status codes and returns JSON error responses with descriptive messages.

Error response format

All error responses follow this structure:

{
  "error": "A human-readable description of what went wrong"
}

Some endpoints include additional fields:

{
  "error": "Validation failed",
  "details": {
    "name": "Name is required",
    "email": "Invalid email format"
  }
}

Status codes

Client errors (4xx)

Server errors (5xx)

Common error scenarios

Missing authentication

GET /api/accounts/my-company/templates
# No session cookie

HTTP/1.1 401 Unauthorized
{
  "error": "Not authenticated"
}

Fix: Sign in to obtain a session cookie.

Insufficient permissions

DELETE /api/accounts/my-company/members/member123
# Authenticated as a Member (not Admin/Owner)

HTTP/1.1 403 Forbidden
{
  "error": "Insufficient permissions"
}

Fix: This action requires Admin or Owner role.

Resource not found

GET /api/accounts/my-company/templates/nonexistent-id

HTTP/1.1 404 Not Found
{
  "error": "Template not found"
}

Fix: Verify the resource ID exists and you have access to the account.

Validation errors

POST /api/accounts/my-company/templates
Content-Type: application/json

{ "name": "" }

HTTP/1.1 400 Bad Request
{
  "error": "Name is required"
}

Fix: Check the request body against the endpoint's required fields.

Best practices

1. Always check status codes — Don't assume success. Check response.ok or the status code.
2. Parse error messages — The error field contains actionable information.
3. Handle 401 globally — Redirect to sign-in when you receive a 401.
4. Log 5xx errors — Server errors are our problem, but logging helps you track impact.
5. Retry on 503 — Service unavailable is temporary. Retry with exponential backoff.