Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xandrlabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

When an ALX Protocol operation fails, the server returns a ProtocolErrorEnvelope. Every error response sets ok to false — a failed request must never return a success envelope. The error.code field is machine-readable and stable across compatible releases, making it safe to branch on in client code. The error.message field is human-readable and intended for developer and operator diagnostics. The optional error.suggestion field may be surfaced to end users or in SDK UX.

​
Error envelope shape

{
  "ok": false,
  "correlationId": "req_123",
  "protocol": {
    "protocol_version": "1.1",
    "capabilities": ["runs"]
  },
  "error": {
    "type": "approval",
    "code": "LOW_CONFIDENCE",
    "message": "Selection confidence 0.22 is below minimum 0.35.",
    "suggestion": "Try a clearer intent or set options.force to override."
  },
  "code": "LOW_CONFIDENCE"
}
The top-level code field is an ergonomic alias. The canonical location is error.code. Always read from error.code in production code.

​
Field reference

FieldRequiredDescription
okYesAlways false for error responses.
correlationIdRecommendedOpaque trace identifier. Include in support requests and logs.
protocolRecommendedResponding protocol version and capabilities.
error.typeYesStable error category. Remains valid even when new codes are added to the category.
error.codeYesMachine-readable, stable error code. Safe to switch on.
error.messageYesHuman-readable description for developers and operators.
error.suggestionNoRemediation guidance. May be shown to end users.

​
Canonical error codes

CodeTypeMeaningClient action
AUTH_REQUIREDauthThe caller has no valid user identity. No credentials were presented.Authenticate the user and retry the request.
UNAUTHORIZEDauthThe caller presented credentials, but they are invalid or mismatched.Refresh credentials and retry.
LOW_CONFIDENCEapprovalThe selected artifact did not meet the minimum confidence threshold.Refine the intent, inspect alternatives, or explicitly set options.force.
NO_ARTIFACT_SELECTEDapprovalNo compatible artifact matched the request parameters.Broaden the input or fetch recommendations.
CONFLICTexecutionIdempotency or in-flight execution conflict — the same operation may already be running.Retry with exponential backoff, or wait for the existing execution to complete.
PAYMENT_REQUIREDbillingBilling or credit state blocks execution.Add credits, update the plan, or route to a lower-cost path.
CONFIG_ERRORconfigA server-side authentication or storage configuration is invalid.Do not retry blindly. Treat as an operator issue and escalate.

​
Retry guidance

Retry only after obtaining fresh credentials. Retrying without new credentials will fail again immediately. AUTH_REQUIRED means no identity was presented; UNAUTHORIZED means the identity was rejected.
Retry only after changing the request inputs or options. Repeating the same request without modification will produce the same result. For LOW_CONFIDENCE, consider whether options.force is appropriate for your use case. For NO_ARTIFACT_SELECTED, broaden the query or consult the recommendations endpoint.
Safe to retry with backoff. The conflict may be transient (a concurrent execution is finishing) or indicate that the idempotency key was already consumed. Wait before retrying and check whether the original operation completed.
Retry only after the billing state has changed — for example, after adding credits or upgrading the plan. Do not implement automatic retry loops that wait for billing changes; surface the error to the user instead.
Do not retry aggressively. This code indicates a server-side misconfiguration, not a transient failure. Alert your operations team and investigate the server logs. Automated retries will not resolve the underlying issue.

​
Handling unknown error codes

Clients must treat unknown error.code values as non-contract-breaking. When you receive an unrecognized code, default to conservative handling — treat it like CONFLICT or surface a generic error to the user. Do not assume any specific retry behavior for an undocumented code.