Api Designer
Shape consistent JSON and RFC 7807 error responses so your solo SaaS or API is easier for agents and frontend clients to handle.
Overview
API Designer is an agent skill for the Build phase that guides consistent JSON and RFC 7807 error response design for HTTP APIs.
Install
npx skills add https://github.com/jeffallan/claude-skills --skill api-designerWhat is this skill?
- Standard nested error object with code, message, and optional field-level details
- RFC 7807 application/problem+json examples with type, title, status, detail, and instance
- Validation error arrays with per-field codes and documentation_url hooks
- Request_id and timestamp patterns for supportable production errors
- RFC 7807 problem detail fields: type, title, status, detail, instance
- Extended validation errors support multiple field-level detail objects
Adoption & trust: 3.6k installs on skills.sh; 9.7k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your API returns ad-hoc error strings and status codes, so clients and agents cannot parse failures or map them to fixes.
Who is it for?
Indie builders defining REST error contracts, migrating to problem+json, or standardizing validation errors before shipping a v1 API.
Skip if: Teams that only need OpenAPI generation with no error-schema work, or pure GraphQL-only stacks where this JSON REST focus does not apply.
When should I use this skill?
Designing or revising HTTP API error responses, validation failure payloads, or RFC 7807 problem details for a backend you are building.
What do I get? / Deliverables
You get copy-pasteable error response patterns—including validation detail arrays—that you can align with OpenAPI and implement in handlers.
- Standard error JSON shapes
- RFC 7807 response examples
- Validation error detail structure
Recommended Skills
Journey fit
Public API contracts and error shapes are defined while you are building the backend, before or alongside route handlers. Error handling, status codes, and problem-details payloads are core backend API design work, not launch or ops monitoring.
How it compares
Design reference for error payloads—not a substitute for an OpenAPI linter or automated contract test suite.
Common Questions / FAQ
Who is api-designer for?
Solo and indie developers building JSON HTTP APIs who want stable error codes, messages, and RFC 7807-style bodies before or while implementing routes.
When should I use api-designer?
During Build (backend) when drafting error schemas, refactoring inconsistent 4xx/5xx responses, or documenting validation failures for SDK and agent consumers.
Is api-designer safe to install?
It is procedural documentation with example JSON; review the Security Audits panel on this Prism page and treat any third-party repo like any other dependency before installing.
SKILL.md
READMESKILL.md - Api Designer
# API Error Handling ## Error Response Design Consistent, informative error responses are critical for API usability. ## Standard Error Format ### Basic Error Response ```json { "error": { "code": "RESOURCE_NOT_FOUND", "message": "User with ID 123 not found", "details": null } } ``` ### RFC 7807 Problem Details Standardized error format (application/problem+json): ```http HTTP/1.1 404 Not Found Content-Type: application/problem+json { "type": "https://api.example.com/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "User with ID 123 does not exist", "instance": "/users/123" } ``` **Fields:** - `type` - URI reference identifying error type - `title` - Short, human-readable summary - `status` - HTTP status code - `detail` - Human-readable explanation specific to this occurrence - `instance` - URI reference for this specific occurrence ### Extended Error Response ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" }, { "field": "age", "code": "OUT_OF_RANGE", "message": "Age must be between 18 and 120" } ], "request_id": "req_123456", "timestamp": "2024-01-15T10:30:00Z", "documentation_url": "https://api.example.com/docs/errors#validation-error" } } ``` ## Error Categories ### 1. Validation Errors (400 Bad Request) Client sent invalid data. ```http POST /users Content-Type: application/json { "name": "", "email": "invalid-email", "age": 15 } Response: 400 Bad Request { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ { "field": "name", "code": "REQUIRED", "message": "Name is required" }, { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" }, { "field": "age", "code": "OUT_OF_RANGE", "message": "Age must be at least 18", "constraints": { "min": 18, "max": 120 } } ] } } ``` ### 2. Authentication Errors (401 Unauthorized) Missing or invalid authentication credentials. ```http GET /users/123 Authorization: Bearer invalid_token Response: 401 Unauthorized WWW-Authenticate: Bearer realm="api", error="invalid_token" { "error": { "code": "INVALID_TOKEN", "message": "The access token is invalid or has expired", "details": { "reason": "token_expired", "expired_at": "2024-01-15T10:00:00Z" } } } ``` **Common auth error codes:** - `MISSING_TOKEN` - No auth token provided - `INVALID_TOKEN` - Token is malformed or invalid - `EXPIRED_TOKEN` - Token has expired - `REVOKED_TOKEN` - Token has been revoked ### 3. Authorization Errors (403 Forbidden) Authenticated but not authorized to perform action. ```http DELETE /users/123 Authorization: Bearer valid_token Response: 403 Forbidden { "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to delete this user", "details": { "required_permission": "users:delete", "your_permissions": ["users:read", "users:update"] } } } ``` ### 4. Not Found Errors (404 Not Found) Resource doesn't exist. ```http GET /users/99999 Response: 404 Not Found { "error": { "code": "RESOURCE_NOT_FOUND", "message": "User with ID 99999 not found", "details": { "resource_type": "User", "resource_id": "99999" } } } ``` ### 5. Conflict Errors (409 Conflict) Request conflicts with current state. ```http POST /users Content-Type: application/json { "email": "existing@example.com", "name": "John Doe" } Response: 409 Conflict { "error": { "code": "RESOURCE_ALREADY_EXISTS", "message": "User with email 'existing