Skip to content

skillBackend and APIs

API Error Responses

Defines one error format with stable machine codes and problem details, then applies it to every endpoint so clients can handle failures reliably.

npx workspacetemplates add api-error-responses --tool claude-code

Writes 1 file to .claude/skills/api-error-responses/

.claude/skills/api-error-responses/SKILL.md28 lines · 1.6 KBFile
---
name: api-error-responses
description: Defines one error format with stable machine codes and problem details, then applies it to every endpoint so clients can handle failures reliably.
---

# API error responses

One error shape, one place that produces it.

## Steps

1. Inventory first. Grep for every place that builds an error response (`res.status(4`, `raise HTTPException`, `ResponseEntity.badRequest`, exception handlers). List the distinct shapes you find.
2. Define the envelope, based on RFC 9457: `type` (a stable URL or slug), `title`, `status`, `detail`, `instance` (the request id), plus `code` (SCREAMING_SNAKE, stable forever) and, for validation, `errors: [{ field, code, message }]`.
3. Build one error class and one global handler. Domain code throws typed errors; only the handler touches status codes and serialization. Set `Content-Type: application/problem+json`.
4. Map consistently: 400 malformed input, 401 no identity, 403 identity but not allowed, 404 missing or hidden, 409 state conflict, 422 failed validation, 429 limited, 500 unexpected.
5. Migrate endpoint by endpoint. Add a contract test per status that asserts the full body shape.

## Rules

- Never return a stack trace, SQL text, file path or internal hostname. Log them with the request id instead.
- Never change a published `code`; add a new one and deprecate the old.
- Messages are for humans and may change; clients switch on `code` only.
- Unexpected errors return a generic 500 body with the request id and nothing else.
- Do not use 200 for failures.

## Report

The shapes found, the new envelope, the files changed, and endpoints you left on the old format with the reason.

What it does

Every API drifts into five error shapes: a bare string here, a framework stack trace there, a 200 with "success: false" somewhere else. Clients end up parsing messages with regular expressions. This skill makes the agent inventory what your endpoints return today and converge on a single format.

The format follows RFC 9457 problem details, plus a stable code string that clients can switch on. The agent also maps exceptions to status codes in one place, so new endpoints inherit the behavior instead of inventing it.

Example

you › Our API returns errors in three different shapes. Unify them.

agent › Found 3 shapes across 41 handlers. Added ApiError and a global handler in src/http/errors.ts using application/problem+json with a stable code field. Migrated 38 handlers and added 9 contract tests. Left /legacy/export on the old shape because a partner depends on it; noted in the report.

Questions

Do I have to use RFC 9457?
No, but starting from a standard saves you design debates and many client libraries already understand it. The skill adapts if your team has a house format.
Will it break existing clients?
It lists any endpoint whose shape changes and asks before touching one that outside consumers rely on.
  • API Pagination Design

    SkillBackend and APIs

    Free
  • API Versioning Strategy

    SkillBackend and APIs

    Free
  • Background Job Design

    SkillBackend and APIs

    Free
  • Caching Strategy

    Skillredis

    Free