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

# Requests, responses & errors

> Request format, response handling, and error codes for the Sutro API.

## Request format

All Sutro endpoints follow REST principles and use standard HTTP methods (`GET`, `POST`, `PUT`, `DELETE`).

Most requests return a response within milliseconds containing the result of the requested action.

### Long-running operations

Some operations—such as generating an application from uploaded attachments—take longer to complete.

Sutro uses a **Request–Monitor–Retrieve** pattern for long-running operations:

1. **Request** — Send a standard HTTP request to start the action. The API responds immediately, confirming that the operation has begun.
2. **Monitor** — Poll a status endpoint to check progress. Continue polling until the status returns `Complete`.
3. **Retrieve** — Once complete, send a follow-up request to the specified endpoint to obtain the final results.

<Note>Webhooks coming soon. With webhooks, polling won't be necessary and Sutro will notify you automatically when an action completes.</Note>

## Response format

Sutro follows REST conventions for responses. Successful requests return `2xx` status codes with JSON payloads containing the requested data or operation confirmation.

## Error codes

### 4xx – Client errors

These indicate an issue with the request itself.

| Status        | Meaning                                                                                            | How to fix                                                             |
| ------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **400**       | Invalid request body or parameters.                                                                | Review request data and correct any formatting or validation issues.   |
| **401**       | Authentication missing or invalid.                                                                 | Include valid credentials or refresh expired tokens.                   |
| **403**       | Authenticated but not authorized.                                                                  | Use credentials with sufficient permissions.                           |
| **404**       | Resource not found or not visible to user.                                                         | Confirm the resource exists and that you have permission to access it. |
| **405 / 406** | Invalid request method or unacceptable format.                                                     | Review API documentation for supported verbs and content types.        |
| **409**       | Request conflicts with current resource state (e.g., trying to remove an active mTLS certificate). | Adjust the resource state first, then retry.                           |
| **429**       | Rate limit exceeded.                                                                               | Wait until the limit resets before retrying.                           |

### 5xx – Server errors

These indicate an issue on Sutro's side.

| Status      | Meaning                                    | What to do                                                                                             |
| ----------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **500–599** | Internal system errors or service outages. | These are automatically logged by Sutro. Contact support if you need details or an ETA for resolution. |

<Note>Always log both the HTTP status and the error payload from the response. This helps you debug client-side issues and improves support turnaround if you need to escalate.</Note>