Copy page

Guides

Errors

Public API failures use an HTTP status and a JSON envelope:

Code
{
  "success": false,
  "error": "Human-readable error message"
}

Status guide

Status	Meaning	Recommended handling
400 Bad Request	The request or connection token is invalid.	Correct the request. Do not retry unchanged input.
401 Unauthorized	API credentials are missing or invalid.	Check both authentication headers.
403 Forbidden	Provider type or permission does not allow the operation.	Use the correct credential or update its permission.
409 Conflict	The requested connection conflicts with existing state.	Treat as a business result and inspect the message.
500 Internal Server Error	Onward could not complete the operation.	Retry with bounded exponential backoff and preserve your correlation context.

Retry policy

Retry only infrastructure and transient server failures. Use exponential backoff with jitter and a maximum number of attempts. Do not automatically retry validation, authentication, authorization, or conflict responses.

Empty data is not an error

GET /v1/quest-chains/active/{platformUserId} returns 200 OK when no active chain exists. Inspect user.exists to distinguish an unknown user from a known user who currently has no active quest chains.

The API Reference lists the responses currently declared for each operation and remains the source of truth for the public contract.