Error Codes

All API errors follow the standard error envelope. This page lists every error code defined in GospeLib.

Error codes are maintained in a single source of truth: data/error-catalog.yaml. Running pnpm codegen:errors regenerates all per-language error files from this catalog.

Error Reference

HTTP Status	Error Code	Default Message	Go Variable	Python Exception
404	PASSAGE_NOT_FOUND	Passage not found	ErrPassageNotFound	PassageNotFoundError
404	CHAPTER_NOT_FOUND	Chapter not found	ErrChapterNotFound	ChapterNotFoundError
404	BOOK_NOT_FOUND	Book not found	ErrBookNotFound	BookNotFoundError
404	TOPIC_NOT_FOUND	Topic not found	ErrTopicNotFound	TopicNotFoundError
404	LEXICON_ENTRY_NOT_FOUND	Lexicon entry not found	ErrLexiconEntryNotFound	LexiconEntryNotFoundError
400	INVALID_REQUEST	Invalid request	ErrInvalidRequest	InvalidRequestError
422	VALIDATION_ERROR	Validation error	ErrValidationError	GospeLibValidationError
401	UNAUTHORIZED	Unauthorized	ErrUnauthorized	UnauthorizedError
403	FORBIDDEN	Forbidden	ErrForbidden	ForbiddenError
429	RATE_LIMITED	Rate limit exceeded	ErrRateLimited	RateLimitedError
500	INTERNAL_ERROR	Internal server error	ErrInternalError	InternalError
503	SERVICE_UNAVAILABLE	Service unavailable	ErrServiceUnavailable	ServiceUnavailableError
502	UPSTREAM_UNAVAILABLE	The upstream service is temporarily unavailable	ErrUpstreamUnavailable	UpstreamUnavailableError
501	NOT_IMPLEMENTED	Not implemented	ErrNotImplemented	FeatureNotImplementedError

Error Response Format

Every error response includes the error code, a human-readable message, and the request ID for log correlation:

{
  "error": {
    "code": "PASSAGE_NOT_FOUND",
    "message": "Passage not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

The request_id matches the X-Request-ID response header. Include it in support requests and bug reports.

Validation Errors

VALIDATION_ERROR (422) responses include a details field with per-field error information:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "request_id": "...",
    "details": {
      "passageId": "Invalid passage ID format. Expected: <bookId>.<chapter>.<verse>"
    }
  }
}

Language Mappings

Go

Error codes are defined as sentinel variables following the Err + PascalCase pattern:

var ErrPassageNotFound = errors.New("PASSAGE_NOT_FOUND")
var ErrValidationError = errors.New("VALIDATION_ERROR")

Python

Error codes map to exception classes. Custom class names are noted in the table above; all others follow the PascalCase + Error pattern:

raise PassageNotFoundError()
raise GospeLibValidationError(details={"passageId": "..."})

Adding New Error Codes

1. Add the new entry to data/error-catalog.yaml
2. Run pnpm codegen:errors to regenerate per-language files
3. Use the generated sentinel/exception in your service code