> ## Documentation Index > Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # API Errors > Error codes and troubleshooting for the AGO Public API All API errors follow a consistent format with a machine-readable `code`, a human-readable `message`, and a link back to this page. ## Error Format ```json theme={null} { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Organization not found with ID '...'.", "param": "org_id", "doc_url": "https://ago.mintlify.app/api/errors#not_found" } } ``` | Field | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | type | Error category (see [Error Types](#error-types) below) | | code | Machine-readable error code | | message | Human-readable description of what went wrong | | param | The request parameter that caused the error, if applicable | | doc\_url | Link to the relevant section on this page | | event\_id | May be present on `internal_error` (500) responses. When included, share this ID with support so they can pull the matching server log. | *** ## Error Types | Type | HTTP Status | Description | | ----------------------- | ----------------------- | -------------------------------------------------- | | `authentication_error` | 401 | Invalid, expired, or missing API key | | `permission_error` | 403 | Valid API key, but missing the required scope | | `invalid_request_error` | 400, 404, 409, 413, 422 | Bad input, missing resource, or validation failure | | `rate_limit_error` | 429 | Too many requests — slow down and retry | | `api_error` | 500 | Internal server error | *** ## Error Codes ### not\_authenticated **Status:** 401 The request did not include a valid API key. Include your key in the `X-API-Key` header: ```bash theme={null} curl -H "X-API-Key: ago_v1_sk_..." https://your-instance.useago.com/api/v1/organizations ``` ### invalid\_api\_key **Status:** 401 The API key is invalid, expired, locked, or revoked. Check your key in **Settings > Integrations > API**. ### insufficient\_scope **Status:** 403 Your API key is valid but does not have the scope required for this endpoint. Each endpoint documents which scope it needs (e.g. `accounts:read`, `conversations:read`, `knowledge:write`). To fix this, edit the API key in **Settings > Integrations > API** and add the required scope. A `write` scope includes `read` access for the same resource. ### not\_found **Status:** 404 The requested resource does not exist. Check that the ID is a valid UUID and that the resource has not been deleted. ### bad\_request **Status:** 400 The request is malformed. Check the `message` and `param` fields for details. ### validation\_error **Status:** 422 One or more request parameters failed validation. The `param` field indicates which parameter is invalid, and `message` describes the issue. ### missing\_required\_parameter **Status:** 422 A required field is missing from the request body. The `param` field tells you which field to add. ### invalid\_parameters **Status:** 422 One or more parameters have invalid values. Check the `message` for specifics (e.g., a UUID that references a non-existent resource). ### conflict **Status:** 409 The operation conflicts with existing data. Common causes: * Creating a resource with a name that already exists * Updating a resource to a state that conflicts with another resource ### too\_many\_items **Status:** 413 A bulk operation exceeds the maximum number of items (100 per request). ### empty\_items **Status:** 422 A bulk operation was sent with an empty items array. At least one item is required. ### creation\_failed **Status:** 500 The resource could not be created due to an internal error. Retry the request. If it persists, contact support. ### update\_failed **Status:** 500 The resource could not be updated due to an internal error. Retry the request. ### deletion\_failed **Status:** 500 The resource could not be deleted due to an internal error. Retry the request. ### export\_failed **Status:** 500 The export operation failed due to an internal error. Try with a smaller date range or retry later. ### request\_too\_large **Status:** 413 The request body exceeds the maximum allowed size. ### rate\_limit\_exceeded **Status:** 429 Your IP address sent too many requests in a short period. The response includes a `Retry-After` header with the number of seconds to wait before retrying. ### concurrency\_limit\_exceeded **Status:** 429 The MCP endpoint (`/api/v1/mcp`) is processing too many requests at the same time. Incoming requests wait briefly for a free processing slot; if none frees up, this error is returned. Wait for the number of seconds in the `Retry-After` header, then retry. If you hit this regularly, reduce the number of MCP calls your client runs in parallel. ### internal\_error **Status:** 500 An unexpected error occurred. The error has been logged. If this persists, contact support with the request details and timestamp. *** ## HTTP Status Summary | Status | Meaning | | ------ | ------------------ | | 200 | Success | | 201 | Resource created | | 400 | Bad request | | 401 | Not authenticated | | 403 | Insufficient scope | | 404 | Not found | | 409 | Conflict | | 413 | Request too large | | 422 | Validation error | | 429 | Too many requests | | 500 | Internal error | *** ## Related Documentation * [Public API Overview](/api/public-api-v1) - Authentication and general API usage * [API Key Authentication](/security/api-key-authentication) - Create and manage API keys