How do I troubleshoot agentOS API errors?

Quick reference: HTTP status codes

2xx — Success

4xx — Client errors

400 Bad Request — Invalid syntax or missing required parameters. Common causes: missing required fields, incorrect data types, malformed JSON, invalid date formats, or field length exceeded. Resolution: Validate your request format, check required fields, and confirm data types match the API specification.

401 Unauthorized — Authentication failed. Common causes: API key not included, invalid key format, expired or revoked key, key not associated with the specified client, or key lacks permission for the requested tier. Resolution: Verify your API key is correct and included in requests. Contact your client to verify key status and tier permissions.

403 Forbidden — API key lacks permission for the resource. Common causes: attempting to access another client's data, rate limit triggered without proper backoff, or request blocked by security policy. Resolution: Check permissions and implement correct throttling with backoff periods.

404 Not Found — The requested resource does not exist. Common causes: incorrect endpoint URL, invalid resource ID, resource has been deleted or archived, or a typo in the path. Resolution: Verify the endpoint URL and resource IDs. Use list endpoints to confirm the resource exists.

405 Method Not Allowed — HTTP method not supported for this endpoint. Resolution: Check the documentation for the correct HTTP method (GET, POST, PATCH, etc.) for each endpoint.

429 Too Many Requests — Rate limit exceeded. Resolution: Implement a 60-second delay before retrying. See the API throttle limits article for full guidance.

5xx — Server errors

500 Internal Server Error — Unexpected server-side error. Resolution: Retry after a short delay. If the error persists, contact api@agentos.com with the request details.

502 Bad Gateway — Invalid response from upstream server. Resolution: Temporary network issue — retry after a few seconds.

503 Service Unavailable — Service temporarily unavailable. Resolution: Retry shortly. If the issue persists for an extended period, contact api@agentos.com.

504 Gateway Timeout — Server did not respond within the timeout period. Resolution: The API timeout is 60 seconds. Use pagination to reduce data size in large requests, and implement retry logic with backoff.

Common integration issues

API key not working (401 errors):

• Confirm the key is correctly formatted with no extra spaces
• Check you're using the correct header: api_key
• Ensure the shortName in the URL matches your key's permissions
• Contact your client to verify key status

Permission denied (403 errors):

• Check that your API key tier includes the endpoint you're trying to access
• Verify you're only accessing data for your authorised client
• Ensure you're not triggering rate limits without proper backoff

Invalid request format (400 errors):

• Confirm JSON syntax is valid (strings quoted, correct escaping)
• Use ISO 8601 date format: YYYY-MM-DDTHH:mm:ss
• Include all mandatory fields in POST/PUT requests
• Match expected data types (string, number, boolean)

Slow responses or timeouts:

• Use pagination for large datasets
• Filter requests with query parameters where available
• Implement caching for frequently accessed data
• Break large operations into smaller chunks

Testing and debugging tools

• Swagger UI — Interactive testing at https://live-api.letmc.com/swagger/ui/index
• Postman — Import OpenAPI schemas for comprehensive testing
• cURL — Command-line testing for quick verification

When to contact support

Reach out to api@agentos.com if you encounter persistent 5xx errors, unexpected API behaviour not covered in documentation, or to request a rate limit increase. Include: the last 5 digits of your API key, the full endpoint URL, the HTTP method, a sample request body (with sensitive data removed), the HTTP status code and response body, the timestamp, and a description of what you expected to happen.