API Responses
API responses contain a status code, headers, and a body. The agent tool must process all three to produce a reliable observation.
Common HTTP Status Codes
200 OK: request succeeded. Body contains the result.
201 Created: resource was created successfully.
204 No Content: action succeeded. No body to return.
400 Bad Request: your request had invalid parameters.
401 Unauthorized: authentication failed or is missing.
403 Forbidden: authenticated but not authorized for this action.
404 Not Found: the requested resource does not exist.
409 Conflict: request conflicts with existing data.
422 Unprocessable: data is correct format but fails validation.
429 Too Many Requests: rate limit exceeded.
500 Internal Server Error: the API server failed.
503 Service Unavailable: API is temporarily down.
Response Processing
- Always check the status code before reading the body
- Handle 4xx errors as the agent's fault (bad request) — do not retry without changing the request
- Handle 5xx errors as the server's fault (server error) — retry after a delay
- Parse the response body as JSON, not as plain text
- Extract only the fields the agent needs — do not pass the entire response as an observation
- Log every API response for debugging and auditing
Key Takeaways
- API responses contain a status code, headers, and a body.
- Always check the status code before reading the body
- Handle 4xx errors as the agent's fault (bad request) — do not retry without changing the request
- Handle 5xx errors as the server's fault (server error) — retry after a delay