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

{
  "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 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:

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 - Authentication and general API usage
• API Key Authentication - Create and manage API keys