Documentation

API v2 Error Reference

Reference every declared API v2 error code, HTTP status, and production trigger.

API v2 errors use a structured error object:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Some validation errors also include an optional details field with field-level information:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body",
    "details": {
      "fieldErrors": {
        "message": ["Too small: expected string to have >=1 characters"]
      }
    }
  }
}

Every v2 response includes an x-request-id header. Include that value when contacting support. Code against error.code; messages and validation details provide human-readable context.

Error Catalog

The table includes all 30 codes declared by API v2. A dash means the code is reserved and has no production v2 call site, so no HTTP status or trigger is currently defined.

CodeHTTP statusWhen it happensNotes
VALIDATION_INVALID_BODY400A request body, path value, query value, limit, cursor, conversation source, source type, or source-processing input fails validation.details is included only when the call site supplies it.
VALIDATION_INVALID_JSON400The chat, retry, tool-result, or feedback endpoint receives a body that is not valid JSON.Other management endpoints parse malformed JSON as an invalid body.
AUTH_MISSING_API_KEY401An authenticated endpoint receives no Authorization header or the value does not start with Bearer .The health endpoint is unauthenticated.
AUTH_INVALID_API_KEY401The bearer API key cannot be validated.Use an active workspace API key.
AUTH_EXPIRED_API_KEY—Reserved; not currently emitted by a production v2 route.No status or trigger is defined.
SUBSCRIPTION_PLAN_REQUIRED403The API key is valid, but its workspace does not have the apiAccess plan feature.API access requires a Hobby plan or above with active billing.
SUBSCRIPTION_API_RESTRICTED_PLAN403A caller enables auto-retrain without plan access, or submits a video URL without video-transcription access.The API key itself remains valid.
AUTH_INSUFFICIENT_PERMISSIONS—Reserved; not currently emitted by a production v2 route.No status or trigger is defined.
AGENT_NOT_FOUND404An agent-scoped request names an agent that does not exist or is not owned by the API key's account.Ownership failures use the same response as missing agents.
RESOURCE_NOT_FOUND404An API v2 conversation required by a detail, message, retry, or feedback operation cannot be found.Mutation and message-list operations only address API v2 conversations.
RESOURCE_DOCUMENT_NOT_FOUND404A source deletion names a document that does not exist for the agent.Invalid non-UUID document IDs instead return VALIDATION_INVALID_BODY.
RESOURCE_MESSAGE_NOT_FOUND404Feedback names an invalid message ID or a message that is not in the specified API v2 conversation.Message IDs are positive numeric values serialized as strings in responses.
RESOURCE_MESSAGE_NOT_ASSISTANT422Feedback targets a message that is not an AI assistant message.User messages and tool records cannot receive feedback.
RESOURCE_TOOL_CALL_NOT_FOUND404The tool-result endpoint cannot match the supplied toolCallId to a pending client action.The call is unknown, expired, or belongs to another API v2 conversation.
QUOTA_CHATBOT_LIMIT403Agent creation would exceed the workspace's chatbot limit.Delete an agent or upgrade before retrying.
QUOTA_STORAGE_LIMIT403Text or Q&A source processing reports a storage limit, a new URL cannot fit within storage, or URL job creation reports a quota failure.Retraining an existing URL does not consume new document storage.
CHAT_MODEL_NOT_ALLOWED403An AI settings update selects a model unavailable on the workspace plan.Choose an allowed model or upgrade the plan.
CHAT_CREDITS_EXHAUSTED—Reserved; not currently emitted by a production v2 route.No status or trigger is defined.
CHAT_AGENT_CREDITS_EXHAUSTED—Reserved; not currently emitted by a production v2 route.No status or trigger is defined.
CHAT_CONVERSATION_MISMATCH404A chat request supplies a well-formed conversationId (≤128 chars) that does not resolve to an API v2 conversation for the agent.A conversationId longer than 128 characters is rejected earlier with 400 VALIDATION_INVALID_BODY, not this code. Omitting conversationId starts a new conversation.
CHAT_RETRY_MESSAGE_NOT_FOUND404Retry receives a non-positive/non-integer message ID, or the target is not an AI assistant message in the API v2 conversation.Tool records are not retry targets.
CHAT_RETRY_NO_USER_MESSAGE400The retry target has no earlier user message to replay.Retry regenerates from the user turn immediately before the selected assistant reply.
INSTAGRAM_NOT_CONNECTED404An Instagram channel request names an agent with no Instagram connection.GET /channels/instagram answers { "connected": false } instead of this code.
INSTAGRAM_RECONNECT_REQUIRED409Comment-to-DM is set live without the comments permission, or conversation starters are published on a connection that is not connected.Reconnect the account under Channels → Instagram in the dashboard.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409A comment_to_dm or story_leads automation is set live while another live instance already targets the same post or story.Turn the other instance off, or target a different post or story. Drafts are never rejected.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409A comment_to_dm or story_leads catch-all (postScope / storyScope "any") is set live while a live catch-all of that kind already exists.Turn the existing catch-all off first, or target a specific post or story.
INSTAGRAM_SYNC_IN_PROGRESS409A persistent-menu or conversation-starters PATCH overlaps another sync of the same resource for the same agent.Retry after the active publish or clear finishes.
INSTAGRAM_SYNC_FAILED502A persistent-menu or conversation-starters sync failed.details.code is an allow-listed failure code; details.http_status and details.meta_code are numeric or null. Meta's message text is never returned, and the stored live snapshot still describes the last confirmed state.
RATE_LIMIT_TOO_MANY_REQUESTS—Reserved; not currently emitted by a production v2 route.No retry timing or Retry-After behavior is defined.
INTERNAL_SERVER_ERROR500URL job creation fails for a non-quota reason, or a non-streaming retry produces no persisted assistant message.Include x-request-id when reporting the failure.