> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swisstools.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes and Responses

> Every error the Swisstools API returns, what each HTTP status code means, and how to handle errors gracefully in your code.

All errors from the Swisstools API return a JSON body with a single `error` field containing a human-readable message. The HTTP status code tells you the category of the problem. There are no nested error objects or machine-readable error codes beyond the status code itself.

## Error Response Shape

Every error response looks like this:

```json theme={null}
{"error": "Unauthorized"}
```

The `Content-Type` header is always `application/json`, even for error responses.

## HTTP Status Codes

| Status                      | Meaning                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | The request body is missing required fields or contains invalid values. Fix the input and retry.    |
| `401 Unauthorized`          | No valid session cookie or API key was supplied. Authenticate and retry.                            |
| `403 Forbidden`             | You are authenticated but do not have permission to access this resource.                           |
| `404 Not Found`             | The resource you requested does not exist, or has been deleted.                                     |
| `405 Method Not Allowed`    | You used an HTTP method that is not supported on this endpoint (e.g., `POST` on a read-only route). |
| `500 Internal Server Error` | Something went wrong on our end. If this persists, contact support.                                 |

## Example Error Responses

**400 — missing required field:**

```json theme={null}
{"error": "Name is required"}
```

**401 — unauthenticated request:**

```json theme={null}
{"error": "Unauthorized"}
```

**404 — resource not found:**

```json theme={null}
{"error": "Not found"}
```

**405 — wrong HTTP method:**

```json theme={null}
{"error": "Method not allowed"}
```

## Handling Errors in Code

Check `res.ok` before reading the response body. When `res.ok` is `false`, parse the JSON and surface the `error` string to your users or logs.

```typescript theme={null}
const res = await fetch('https://swisstools.dev/api/projects/proj-id/mocks', {
  headers: { 'Cookie': sessionCookie }
});

if (!res.ok) {
  const { error } = await res.json();
  console.error('API error:', error);
  // Handle specific status codes
  if (res.status === 401) {
    // Redirect to login
  } else if (res.status === 404) {
    // Show not-found UI
  }
}
```

```python theme={null}
import requests

res = requests.get(
    'https://swisstools.dev/api/projects/proj-id/mocks',
    cookies={'session': session_token}
)

if not res.ok:
    error = res.json().get('error')
    print(f'API error {res.status_code}: {error}')
```