API Error Documentation

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/api-error-documentation/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Standardized error responses with stable error codes, field-level detail, and linked documentation. Every 4xx and 5xx response includes a code that maps to a solution guide. Developers debug faster with error context.

The problem

Developers get HTTP 422 errors and don’t know what field caused it; debugging takes hours. ‘Invalid field’ gives no path; ‘Try again later’ on 500 hides the real issue and they can’t file support tickets without a reference.

What it does

• Standardized error response format: {code, message, field, suggestion, correlation_id}
• HTTP 422 validation errors list ALL failing fields (not just the first one)
• HTTP 400 bad request errors include JSON path to malformed field
• HTTP 401/403 errors explain why (missing API key, key lacks scope, IP not allowlisted)
• HTTP 500 errors include a correlation ID for support tickets
• Stable error code registry (e.g., PRODUCT_SKU_DUPLICATE, ORDER_TOTAL_MISMATCH)
• Documentation page per error code with example fix
• OpenAPI schema documents all possible error codes per endpoint
• Error codes never change meaning (backward compatibility guarantee)
• Admin error log showing recent errors by code and frequency

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Localized error messages in multiple languages (reason: belongs to paid localization service; core is English only)
• Machine-readable error suggestions (reason: error docs are for human developers; ML fixes belong to paid IDE integration)
• Automatic error reporting to Sentry/Rollbar (reason: belongs to paid monitoring addon; core only gives developers the correlation ID)
• Error deduplication/aggregation (reason: analytics belong to paid analytics addon)

Data model

none

API

• GET /api/errors
• GET /docs/errors

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Error log viewer showing recent errors by code. Error frequency chart (what’s breaking most). Search errors by code or keyword. Correlation ID lookup (search by ID to find context).

The seam — why this is core

Core owns the error catalog, response format, and documentation. Error clarity is infrastructure; not a per-country obligation or credential. Paid integrations document their own error codes.

Core owns the interface + honest error catalog; error clarity is infrastructure, not a per-country obligation or credential.

Dependencies

• Existing API framework (must intercept all errors globally)
• Documentation generation system
• Request correlation ID middleware

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A 422 response for product creation lists all failing fields (SKU, name, price) not just the first one
• A 422 response includes an error code (e.g., PRODUCT_VALIDATION_FAILED) and that code appears in error docs
• HTTP 401 error message explains ‘Missing X-API-Key header’ (not just ‘Unauthorized’)
• HTTP 403 error message explains ‘Your API key lacks scope: products:write’ (not just ‘Forbidden’)
• HTTP 500 error includes a correlation ID that a developer can search in support tickets
• Error codes are documented with example request/response and a fix
• OpenAPI schema for /products/create lists all possible error codes
• A validation error for duplicate SKU includes the conflicting product ID

Risks

If error codes change meaning, developers apply fixes to wrong problems. If correlation IDs are not unique, support tickets get matched to wrong errors. If 500 errors don’t include correlation IDs, developers can’t debug them. If error docs are not updated with new validation rules, developers see outdated solutions.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.