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.
Tracking-link creation failures
Creating a tracking link runs in the background, so most refusals arrive later, in theerror 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.