Repository navigation
EN Observability
English · Türkçe · Languages / Diller
Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English
| Endpoint | Meaning |
|---|---|
/health |
Cheap process liveness |
/ready |
Readiness based on dependencies/projects |
| Configured metrics path | Prometheus output when enabled |
<prefix>/meta |
Project metadata subject to authorization |
<prefix>/_openapi.json |
The project's actual endpoint contract |
/health=200 does not establish that every application is healthy. No active apps, an invalid app or dependency failures can produce /ready=503. Detailed readiness can identify application names and error types, without exposing secrets.
OPERATOR_TOKEN is a separate credential for detailed readiness/metrics. Send X-Forge-Operator-Token or the appropriate Bearer header. An application key does not grant process-level operator access, and an absent token does not authorize the caller.
| Status | Typical cause | First check |
|---|---|---|
| 400 | Invalid JSON/parameter or missing idempotency header | Actual endpoint contract |
| 401 | Missing/invalid credential or consumed bootstrap | Credential type and lifetime |
| 403 | Permission, host/IP/HTTPS or scope rejection | Principal and server policy |
| 404 | Missing/invisible route or row | Prefix, action, tenant/owner |
| 409 | Revision, rowcount, idempotency or business conflict | Previous state and key |
| 413 | Body/file/result limit | Both proxy and Forge limits |
| 422 | Schema/type/field violation | JSON schema and field allowlists |
| 429 | Rate budget exceeded | Retry-After and client-IP resolution |
| 503 | Saturation, dependency or readiness failure | Readiness, DB, Redis, concurrency |
These are typical categories, not a guarantee that each endpoint returns every listed status. Error bodies also depend on the endpoint/model.
Request IDs correlate client and server diagnostics. SDK ForgeResponse exposes request_id, cache_status and idempotent_replay. The SDK preserves a request ID through one retry chain; it is not the business idempotency key.
Monitor request counts, latency, cache behavior and audit queue/drop/write-failure signals together. Averages can hide queueing and tail latency. Avoid logging tokens, complete bodies and personal data by default.
Application audit and Editor security audit serve different purposes. Alert on dropped audit entries and write failures. Application-level append-only design is not cryptographic immutability against a database administrator or a regulatory certification. Protect operational access and backups separately.
This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.
main/framework/factory.pymain/framework/observability.pymain/framework/audit.pymain/docs/32-API-Semantics-and-HTTP-Contracts.md