API Errors

Error codes and troubleshooting for the AGO Public API

Errors handled by the shared REST error handler use a machine-readable code and a human-readable message, often with a documentation link. MCP can instead return JSON-RPC errors or session errors containing only type and message; clients must not assume every error has the REST fields below.

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, when available
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 or not allowed for this feature
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

invalid_api_key

Status: 401

The request did not include a valid API key: the key is missing, invalid, expired, locked, or revoked. 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

Check your key in Developer > API Keys.

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 Developer > API Keys 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: 422

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.

ambiguous_addressing

Status: 422

A bulk operation identified the same resources two different ways at once. POST /documents/bulk-delete accepts either document_ids or source_id + page_ids, not both in the same request.

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. When calling the API from a browser, Retry-After is readable from JavaScript on the 429 response, and CORS preflight (OPTIONS) requests do not count towards the limit.

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.

---

Tasks

The Tasks API and the MCP task tools return these codes in the same error envelope.

staff_principal_required

Status: 403

Tasks can only be used by active staff users. The API key’s creator, the OAuth user or the session user is not, or is no longer, an active staff user. Create the key from an active staff account, or reconnect OAuth as one.

tasks_disabled

Status: 403

Tasks is not enabled for your workspace. Contact AGO to enable it.

task_not_found

Status: 404

No task exists with this ID. It may have been deleted.

link_target_not_found

Status: 404

The conversation, ticket, feedback, message or knowledge update request you tried to link does not exist. Check target_type and target_id.

task_revision_conflict

Status: 409

The task changed since the expected_revision you sent. Read the task again, reapply your change and retry. param is expected_revision.

stale_neighbors

Status: 409

The cards you passed as before_task_id or after_task_id moved, or are no longer next to each other. Read the board again and retry the move.

status_option_in_use

Status: 409

A status still has tasks and cannot be archived until you choose where to move them.

status_option_required

Status: 400

The board needs this status: the review status, the last to-do status and the last done status cannot be archived. Also returned when a task is created without a status and no to-do status is active.

invalid_color

Status: 400

The color is not one of the 8 colors available for statuses and labels. The message lists the valid colors.

bulk_items_invalid

Status: 400

A bulk action on tasks must name between 1 and 100 existing tasks. The message lists unknown task IDs.

idempotency_key_reused

Status: 409

The Idempotency-Key (or MCP idempotency_key) was already used with a different request body in the last 24 hours. Use a new key for a different request.

Invalid filter or field values

Status: 400

A filter or field has an unknown value, for example invalid_status, invalid_priority, invalid_queue or invalid_sort. The message lists the valid values and param names the field.

---

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