# API Error Envelope

> > **Worked example.** The envelope below is a fictional "Acme API" house contract.

- Skill: `decimal-labs/api-error-envelope` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add decimal-labs/api-error-envelope`
- Raw SKILL.md: https://api.skillmd.com/api/skills/decimal-labs/api-error-envelope/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: decimal-labs (https://skillmd.com/u/decimal-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/decimal-labs/api-error-envelope

---


> **Worked example.** The envelope below is a fictional "Acme API" house contract.
> It's a shape a model *cannot* guess from training — which is the whole point: the
> with-skill vs without-skill delta this example measures is real knowledge-lift
> (our exact envelope), not generic JSON competence. Fork this skill and drop in
> your own API's contract.

# Acme API — Error Response Envelope

Every error response body our API returns MUST be this exact shape — no more, no less:

```json
{
  "error": {
    "code": "SCREAMING_SNAKE_CASE",
    "message": "A human-readable, client-safe sentence.",
    "request_id": "the request's correlation id"
  }
}
```

Rules a model cannot guess without this skill:

- The payload is **nested under a top-level `error` object** — never a bare `{"message": ...}` or a
  flat `{"error": "..."}` string.
- `code` is **SCREAMING_SNAKE_CASE** (e.g. `NOT_FOUND`), never an HTTP number, never lowercase, never
  a sentence. Use our vocabulary: `NOT_FOUND`, `VALIDATION_ERROR`, `UNAUTHORIZED`, `RATE_LIMITED`,
  `INTERNAL`.
- `message` is a human-readable sentence safe to show a client — no stack traces, no internals.
- **`request_id` is REQUIRED on every error** so clients can quote it in support tickets. Omitting it
  is the single most common way a hand-written error body fails our contract.

## When to use

Load this skill only when writing an **error response body** for the Acme API. Do not impose the
envelope on a plain factual answer or a success body — see the non-activation case in `eval.yaml`.

## Output

Return **only** the JSON error body — no prose, no code fence, no explanation.