ambleloftErrors and troubleshooting
Use error codes to choose the next step and business state to decide whether a retry is valid.
API REFERENCE
Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.
On this page
01Validation and authorization
Fix declarations, input and grants rather than hiding contract errors behind retries.
| Field / API | Contract |
|---|---|
| INVALID_ARGUMENT / INVALID_OUTPUT | Input/output violates the contract; inspect schemas and bindings. |
| NOT_FOUND / UNSUPPORTED | Missing resource or unsupported host; check versions and IDs. |
| UNTRUSTED / DISABLED / FORBIDDEN | Check trust, enablement and invocation scope. |
| GRANT_REQUIRED / INTERACTION_REQUIRED | Use host page interaction to obtain consent; the Agent cannot fake confirmation. |
02Runtime and concurrency
Keep requestId and effectStatus. Query uncertain business outcomes, especially before repeating writes.
| Field / API | Contract |
|---|---|
| CANCELLED / TIMEOUT / OUTCOME_UNKNOWN | Cancellation or timeout does not prove non-execution; query submissionId / invocationId. |
| BUSY / CONFLICT | Handle concurrency and revision conflicts; reread before deciding. |
| ACTIVATION_FAILED / HOST_UNAVAILABLE | Inspect activation logs and host/service availability. |
| STORAGE_UNAVAILABLE / QUOTA_EXCEEDED | Check storage availability or quota; avoid retry loops. |
| INTERNAL | Preserve diagnostics; unknown handler errors may map to INTERNAL. |
03Diagnose common symptoms
Trace the chain: package → declaration → activation → discovery → confirmation → business service → output schema.
| Field / API | Contract |
|---|---|
| Icon missing | Verify packaged assets, static PNG format and host compatibility. |
| Form missing | Check Skill directories, relative amble-form-ref paths and model tool calls. |
| Operation missing | Check id, handler registration, exposeTo, enablement and permissions. |
| No message | Check UNSUPPORTED, publish status, receive/muted preferences and connection. |
| Action never completes | Handler return is not completion; inspect reportActionResult. |
SDK / CLI 0.1.0-alpha.9 · Contract baseline Compatibility and preview notes · Sample source