Skip to main content
Every error from https://api.onlyx.ai/v1 has the same shape:
Every response, success or error, also carries an X-Request-Id header. You can send your own X-Request-Id (8 to 64 letters, digits and dashes) to correlate OnlyX requests with your logs; OnlyX echoes it back. Without one, OnlyX creates an id of the form req- followed by 24 hex characters.

All error codes

Authentication and permission

Not found

The API answers 404 for anything in another workspace or outside your creator restriction, with the same body as for an id that never existed. It never confirms that such an id exists. If OnlyX ever switches the public API off, every path answers 404 NOT_FOUND too, indistinguishable from a path that does not exist.

Bad requests and conflicts

Sending

Limits and slow reports

Temporarily unavailable

Server

Which errors to retry

Always retry writes with the same Idempotency-Key, so a request that actually succeeded is not performed twice. A message delivered with status unconfirmed is not an error and must not be retried; see Read and send messages.

Handling errors in code

OAuth endpoint errors

The OAuth endpoints (/oauth/token, /oauth/register) follow the OAuth standards instead of the envelope above, for example {"error": "invalid_grant", "error_description": "..."}. AI clients handle these for you. See Authentication. On the OnlyX consent screen, an OnlyX support person who is signed in to your workspace to help you cannot approve or deny an app connection (403 SUPPORT_SESSION_FORBIDDEN, “A support session cannot connect apps to the customer’s workspace or answer their requests.”). An owner or admin of the workspace must approve it personally. Creating a tracking link runs in the background, so most refusals arrive later, in the error of GET /v1/creators/{creatorId}/tracking-links/creations/{creationId} with state: "failed", not as an HTTP error. The link was not created. error.code is one of these (more may be added, so handle unknown codes like CREATION_FAILED): See Tracking links.