Error Codes

All OutX API errors return a JSON object with an error field containing a human-readable message.

{
  "error": "Error message here"
}

400, Bad Request

Missing or invalid parameters. Check the error message for specifics. Watchlist endpoints:

Error Message	Cause
`Either keywords array or prompt string is required`	Keyword/Reddit watchlist create with neither mode supplied
`Provide either keywords or prompt, not both`	Keyword/Reddit watchlist create with both modes at once
`keywords array is required and must not be empty`	Watchlist update: `keywords` passed but empty or not an array
`No valid keywords provided after cleaning`	All keywords are invalid/empty after normalization
`profiles array is required and must not be empty`	People watchlist: `profiles` missing, not an array, or empty
`No valid profile identifiers provided`	No profiles passed validation
`companies array is required and must not be empty`	Company watchlist: `companies` missing, not an array, or empty
`No valid company identifiers provided`	No companies passed validation
`Invalid fetchFreqInHours`	Must be one of: 1, 3, 6, 12, 24, 48, 72
`Missing required parameter: id`	Watchlist update/delete called without `id`
`Name cannot be empty`	Watchlist update with empty name
`No valid update fields provided`	Watchlist update with nothing to change
`disable must be a boolean value`	Watchlist enable/disable with invalid value
`idempotency_key must be a string`	`idempotency_key` was sent as a number, object, or other non-string
`idempotency_key must be 128 characters or fewer`	`idempotency_key` was longer than the 128-character limit
`watchlist_id is required and must be a string`	Get Posts / Get Interactions without a `watchlist_id`
`Invalid watchlist ID: <id>`	Get Posts / Get Interactions: `watchlist_id` doesn’t exist
`Unknown query parameter(s): ...`	Get Posts: an unrecognized parameter was sent, e.g. `limit`, `offset`, `per_page`, or `pageSize` instead of `page`/`page_size`. The message lists the offending names, a did-you-mean suggestion where the alias is close enough to an accepted name (`limit -> page_size`, `pageSize -> page_size`, `offset -> range_from`; `per_page` gets no specific hint), and all accepted parameters in every case.
`Invalid value(s) for <param>: ...`	Get Posts: `sort_by`, `relevance_level`, or `seniority_level` got a value outside its allowed set. The message lists the allowed values.

Engagement endpoints:

Error Message	Cause
`Missing required parameter: post_id`	Like/comment without `post_id`
`Missing required parameter: user_email`	Like/comment without `user_email`
`Missing required parameter: comment_text`	Comment without `comment_text`
`comment_text cannot be empty`	Comment with empty or whitespace-only text
`Invalid actor_type. Must be 'user' or 'company'`	`actor_type` not `"user"` or `"company"`
`company_title is required when actor_type is 'company'`	Engaging as company without providing company name
`Post does not support like functionality (missing social_urn)`	Post has no activity URN (may be deleted)
`Post does not support comment functionality (missing social_urn)`	Post has no activity URN (may be deleted)

LinkedIn Data endpoints:

Error Message	Cause
`Missing or invalid 'profile_slug'`	`fetch-profile` without a valid `profile_slug` string
`Missing or invalid 'profile_urns' (must be a non-empty array)`	`fetch-profiles-posts` without a valid array of URNs
`Missing or invalid 'social_urn'`	`like-post` or `comment-post` without a valid `social_urn`
`Missing or invalid 'comment_text'`	`comment-post` without a valid `comment_text`
`Missing or invalid 'api_agent_task_id'`	`get-task-status` without a valid task ID
`Missing or invalid 'email'`	Auth endpoints without a valid email
`Missing or invalid 'otp'`	`auth-verify-otp` without a valid OTP code

401, Unauthorized

API key is missing or invalid.

Error Message	Cause
`Missing API Key`	No `x-api-key` header in the request
`Invalid API Key`	The API key does not match any team
`Invalid or expired OTP`	OTP code is incorrect or has expired (auth-verify-otp)

Fix: Include your API key in the x-api-key header. Get your key at mentions.outx.ai/api-doc.

402, Plan Limit Reached

Your team has hit a plan-based limit. The error message includes your current limit.

Error Message Pattern	Cause
`Your plan includes up to N watchlists...`	Watchlist count limit reached
`Your plan includes total of N likes...`	Daily like limit reached (resets at UTC midnight)
`Your plan includes total of N comments...`	Daily comment limit reached (resets at UTC midnight)
`Your plan includes total of N team members...`	Team member invitation limit reached
`Your plan allows up to N posts per week per watchlist...`	Weekly post fetch limit per watchlist reached
`Your plan allows up to N active AI agents per watchlist...`	Auto-engagement rule limit per watchlist reached

Fix: Upgrade your plan at outx.ai/pricing or wait for daily/weekly limits to reset. Plan limits by tier:

Limit	Free	Growth	Expert	Ultimate
Watchlists (all four types combined)	2	5	20	100
Team members	5	10	25	Unlimited
Auto-engagement rules per watchlist	1	2	5	10
Profiles or companies per people or company watchlist	200	200	200	200
Tracked profiles and companies across the team	400	1,000	4,000	20,000
Posts per watchlist per week	2,000	15,000	15,000	15,000
Historical data (how long a post is kept)	28 days	45 days	180 days	720 days

Notes on the table:

The weekly post limit counts posts with a relevance score of 4 or higher. Free teams whose extension and human activity have gone quiet for a while are limited to 100 posts per watchlist per week.
pro is a legacy plan identifier. It carries the same limits as growth. There is no enterprise plan on the API.
These are quotas on how much you can have, not on how often you can call the API. There is no request rate limit on any plan.
Hitting a quota returns 402 with a message naming the limit. See Error Codes.

403, Forbidden

Access denied. Most commonly caused by the Chrome extension not being active.

Error Message	Cause
`Plugin installation required: Please install the OutX browser extension on at least one team member's account to use the API. The plugin must have been active within the last 48 hours.`	No team member has an active Chrome extension
`Access denied: You don't have permission to access this resource`	Trying to access another team’s resources
`Access denied: You don't have permission to access these watchlists`	Trying to access watchlists from another team
`Access denied: You don't have permission to interact with this post`	Trying to engage with a post from another team’s watchlist

Fix for plugin error: Install the OutX Chrome extension, sign into LinkedIn in the same browser, and keep the browser open. The extension must have been active within the last 48 hours. See Chrome Extension Guide.

The 403 plugin error is the most common API issue. If you’re getting this error, check that:

The Chrome extension is installed on at least one team member’s browser
That browser has been open within the last 48 hours
The team member is signed into LinkedIn in the same browser

404, Not Found

The requested resource does not exist or belongs to a different team.

Error Message	Cause
`Agent task not found`	LinkedIn Data task ID does not exist or belongs to another team
`Watchlist not found or access denied`	Watchlist ID does not exist, isn’t the requested type (keyword/reddit/people/company), or belongs to another team. Returned on GET, PUT, and DELETE. Note: each endpoint only sees its own type, so asking `/api-keyword-watchlist` for a Reddit watchlist’s ID returns 404.
`List not found or access denied`	Creating watchlist with a `list_id` that doesn’t exist
`Post not found`	The `post_id` in a like/comment request does not exist
`Tracking list not found`	The post’s associated watchlist no longer exists
`User not found with email: [email]`	The `user_email` is not a member of your team
`Company not found`	The `company_title` does not match any company page for the admin user
`No admin user found in the team`	LinkedIn Data engagement, your team has no admin members
`No company admin found for the specified company`	No admin user manages the specified company page

409, Conflict (Disabled Watchlist)

{
  "error": "This watchlist is disabled. Enable it before updating it."
}

You sent a PUT /api-keyword-watchlist or PUT /api-reddit-watchlist against a paused watchlist. A disabled watchlist rejects updates so a paused list cannot be silently mutated or backfilled. The one request that gets through is an explicit re-enable: a patch-mode PUT carrying disable: false is allowed, otherwise a paused watchlist could never be turned back on. Prompt mode has no such exception, so you cannot re-enable and re-prompt in one call: re-enable first, then send the new prompt. Fix: Re-enable first, then retry the update:

curl -X PUT "https://api.outx.ai/api-keyword-watchlist" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "id": "YOUR_WATCHLIST_ID", "disable": false }'

Check whether a watchlist is disabled via the disabled field on the type’s GET endpoint (GET /api-keyword-watchlist?id=... or GET /api-reddit-watchlist?id=...).

422, Prompt Not Specific Enough

Keyword and Reddit watchlists only, on a prompt-mode create or update. The prompt is checked before anything is written, so a 422 means nothing was created and nothing on an existing watchlist was changed. This is one of the two error bodies that carry more than an error field (the other is the 503 below):

{
  "error": "prompt_not_specific_enough",
  "reason": "This says what you want back but not what it should be about. Name the product, category or competitor and we can build the feed.",
  "missing": ["topic"],
  "detected": { "words": 3, "chars": 15, "intent_terms": ["buyers"] },
  "example": "Founders asking which CRM to buy after outgrowing spreadsheets",
  "question": "Buyers of what? Name the product, category, or competitor."
}

Field	Meaning
`error`	Always `prompt_not_specific_enough`
`reason`	Plain-English explanation, safe to show a user
`missing`	Which slots are at fault. From the prompt check: `topic`, `audience`, `signal`. From a `strict` refusal: the inferred slots, drawn from `topic`, `audience`, `signals` (plural here), `competitors`, `use_case`, `excluded`. Treat it as a list of strings, not a fixed enum.
`detected`	What the check actually saw, for debugging
`example`	A rewritten prompt of the same shape that would pass
`question`	Only present when one answer would fix it. Relay it to your user word for word, then retry with their answer in the prompt.

Prompts refused this way: one with no subject in it (“find me buyers”), an unfilled [PLACEHOLDER], a bare LinkedIn profile link (use a people watchlist), a bare URL, a request for engagement on your own posts, keyboard mashing, and anything under 6 words or 30 characters. error, reason, missing, detected and example are always present. question is the only optional one. The same status and body shape are returned when you send strict: true on a prompt-mode create and the prompt left something to be inferred. There, missing lists the inferred slots and detected.interpretation shows how the prompt was read. Fix: ask your user the question if there is one, otherwise rewrite the prompt in the shape of example. Do not guess a topic on the user’s behalf.

503, Interpretation Unavailable

{
  "error": "interpretation_unavailable",
  "message": "strict was set but the prompt could not be interpreted right now. Retry, or drop strict to create with inferred values."
}

Only reachable on a prompt-mode create with strict: true. Nothing was created. Both error and message are always present. Retry, or drop strict and accept inferred values.

405, Method Not Allowed

{
  "error": "Method GET not allowed"
}

You used the wrong HTTP method. Check the endpoint documentation for the correct method (GET, POST, PUT, DELETE).

429, not used

No OutX endpoint returns 429 for request volume. There is no API request quota on any plan. What is capped is the LinkedIn-side work your calls trigger, and that surfaces as a queued task, not an HTTP error. See Rate Limits. The one exception is POST /linkedin-agent/send-connection-request, which returns 429 with LinkedIn invitation limit reached when LinkedIn’s own weekly invitation cap is hit; that is LinkedIn’s limit, not a request quota, and the retry is the following week.

500, Internal Server Error

An unexpected error occurred on our side. Retry with exponential backoff. If the error persists, contact support@outx.ai.

Error Response Format

Every error, on every endpoint, is a JSON object with a single error field:

{
  "error": "Human-readable error message"
}

Parse the HTTP status for the category and the error string for specifics. The one exception is the prompt refusal (422 and the strict-only 503), where error is a stable machine-readable code (prompt_not_specific_enough, interpretation_unavailable) and the body carries extra fields to act on. See 422 above.

Frequently Asked Questions

Why am I getting a 403 error even though my API key is correct?

The most common cause is the Chrome extension requirement. At least one team member must have the OutX Chrome extension installed and actively used within the last 48 hours. Install the OutX Chrome Extension, sign into LinkedIn in the same browser, and keep the browser open.

What does 'Plugin installation required' mean?

OutX retrieves LinkedIn data through real browser sessions via the Chrome extension. This error means no team member has had the extension active recently. The extension runs in the background, just keep Chrome open with the extension installed and it will stay active.

How do I fix a 402 plan limit error?

402 errors mean you’ve reached a limit on your current plan. You can either upgrade your plan at outx.ai/pricing, wait for daily/weekly limits to reset, or delete existing resources (like watchlists) to make room for new ones.

Do daily limits reset at a specific time?

Yes. Daily limits (likes, comments) reset at UTC midnight (00:00 UTC). Weekly limits (posts per watchlist) reset on Monday at 00:00 UTC.

Getting Started

Authentication (OTP)

Keyword Watchlist

People Watchlist

Company Watchlist

Reddit Watchlist

Posts & Engagement

Team & Usage

LinkedIn Data

Integrations

Error Codes

Error Codes

400, Bad Request

401, Unauthorized

402, Plan Limit Reached

403, Forbidden

404, Not Found

409, Conflict (Disabled Watchlist)

422, Prompt Not Specific Enough

503, Interpretation Unavailable

405, Method Not Allowed

429, not used

500, Internal Server Error

Error Response Format

Frequently Asked Questions

​Error Codes

​400, Bad Request

​401, Unauthorized

​402, Plan Limit Reached

​403, Forbidden

​404, Not Found

​409, Conflict (Disabled Watchlist)

​422, Prompt Not Specific Enough

​503, Interpretation Unavailable

​405, Method Not Allowed

​429, not used

​500, Internal Server Error

​Error Response Format

​Frequently Asked Questions

Error Codes

400, Bad Request

401, Unauthorized

402, Plan Limit Reached

403, Forbidden

404, Not Found

409, Conflict (Disabled Watchlist)

422, Prompt Not Specific Enough

503, Interpretation Unavailable

405, Method Not Allowed

429, not used

500, Internal Server Error

Error Response Format

Frequently Asked Questions