# API Documentation

Standardized error taxonomy with HTTP/status semantics, structured payload contracts, and retry guidance by failure class.

## Errors

### Error Response Format

All errors return a JSON object with an `error` field describing the issue.

```json
{
  "error": "error_code_here"
}
```

### HTTP Status Codes

- **400**
  - Bad Request — Invalid request body, missing required fields, or malformed input.

- **401**
  - Unauthorized — Missing or invalid API key, or token has been revoked/expired.

- **403**
  - Forbidden — API key lacks required scopes for this endpoint.

- **404**
  - Not Found — Resource does not exist or has been deleted.

- **429**
  - Too Many Requests — Monthly usage limit exceeded. Please reach out to **mnexium** for assistance.

- **500**
  - Internal Error — Server error. Contact support if persistent.

### Common Error Codes

- `unauthorized`  
  - **401**  
    API key is missing, invalid, or malformed.

- `token_revoked`  
  - **401**  
    API key has been revoked. Generate a new one in the dashboard.

- `token_expired`  
  - **401**  
    API key has expired. Generate a new one in the dashboard.

- `forbidden`  
  - **403**  
    API key doesn't have the required scope (e.g., `prompts:write`).

- `prompt_not_found`  
  - **404**  
    The specified prompt ID does not exist.

- `usage_limit_exceeded`  
  - **429**  
    Monthly usage limit exceeded. The response includes `current` and `limit` fields showing your usage.

- `subject_id_required`  
  - **400**  
    `subject_id` is required when `history: true`.

- `name_required`  
  - **400**  
    Missing required `name` field when creating a prompt.

- `prompt_text_required`  
  - **400**  
    Missing required `prompt_text` field when creating a prompt.