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:- Request — Send a standard HTTP request to start the action. The API responds immediately, confirming that the operation has begun.
- Monitor — Poll a status endpoint to check progress. Continue polling until the status returns
Complete. - Retrieve — Once complete, send a follow-up request to the specified endpoint to obtain the final results.
Webhooks coming soon. With webhooks, polling won’t be necessary and Sutro will notify you automatically when an action completes.
Response format
Sutro follows REST conventions for responses. Successful requests return2xx 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. |
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.