Error Codes

Complete reference of error codes returned by the Reports Service API.

Error Response Format

All errors follow the standard EventZR envelope format with structured error objects.

Error response examplejson

{
  "data": null,
  "error": {
    "code": "ERR_REPORTS_TEMPLATE_NOT_FOUND",
    "message": "Report template with ID 'abc123' not found",
    "http": 404
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "service": "reports-svc",
    "timestamp": "2026-02-24T19:00:00.000Z"
  }
}

Error Code Reference

Code	HTTP	Description
`ERR_REPORTS_NOT_FOUND`	404	Report template, export, or schedule not found
`ERR_REPORTS_TEMPLATE_NOT_FOUND`	404	Report template does not exist
`ERR_REPORTS_EXPORT_NOT_FOUND`	404	Export job does not exist
`ERR_REPORTS_SCHEDULE_NOT_FOUND`	404	Scheduled report does not exist
`ERR_REPORTS_WEBHOOK_NOT_FOUND`	404	Webhook registration not found
`ERR_REPORTS_DELIVERY_NOT_FOUND`	404	Webhook delivery record not found
`ERR_REPORTS_DUPLICATE`	409	Resource already exists (duplicate name/slug)
`ERR_REPORTS_TEMPLATE_ARCHIVED`	409	Template is archived and cannot be modified
`ERR_REPORTS_EXPORT_ALREADY_COMPLETED`	409	Export job already completed, cannot cancel
`ERR_REPORTS_EXPORT_NOT_FAILED`	409	Only failed exports can be retried
`ERR_REPORTS_VALIDATION_FAILED`	400	DTO validation failed
`ERR_REPORTS_INVALID_TEMPLATE`	400	Template configuration is invalid
`ERR_REPORTS_INVALID_CRON`	400	Invalid cron expression for schedule
`ERR_REPORTS_INVALID_FORMAT`	400	Unsupported export format (use csv, xlsx, pdf, json)
`ERR_REPORTS_FILE_TOO_LARGE`	400	Report output exceeds maximum file size
`ERR_REPORTS_QUOTA_EXCEEDED`	429	Daily or monthly report generation quota exceeded
`ERR_REPORTS_RATE_LIMITED`	429	Too many requests, rate limit exceeded
`ERR_REPORTS_UNAUTHORIZED`	401	Missing or invalid JWT token
`ERR_REPORTS_FORBIDDEN`	403	Insufficient permissions for this operation
`ERR_REPORTS_SUBSCRIPTION_REQUIRED`	403	Feature requires higher subscription tier
`ERR_REPORTS_BOOTSTRAP_FAILED`	503	Service is still initializing, please retry
`ERR_REPORTS_GENERATION_FAILED`	500	Report generation failed (rendering/data error)
`ERR_REPORTS_S3_UPLOAD_FAILED`	500	Failed to upload report to S3
`ERR_REPORTS_WEBHOOK_DELIVERY_FAILED`	500	Webhook delivery failed after all retries
`ERR_REPORTS_AI_NARRATIVE_FAILED`	500	AI narrative generation failed

HTTP Status Code Summary

Status	Meaning	When
`200`	OK	Successful GET, PUT, DELETE, or toggle operations
`201`	Created	Resource created (template, schedule, webhook)
`202`	Accepted	Export job queued for background processing
`400`	Bad Request	Validation failure, invalid parameters
`401`	Unauthorized	Missing or expired JWT token
`403`	Forbidden	Insufficient role or subscription tier
`404`	Not Found	Resource does not exist
`409`	Conflict	Duplicate resource or invalid state transition
`429`	Too Many Requests	Rate limit or quota exceeded
`500`	Internal Error	Generation failure, S3 error, AI error
`503`	Service Unavailable	Lambda bootstrap in progress