Skip to content

Reference

Errors should be actionable

Every failure has a transport status and a stable v1 error envelope. SDKs turn common failures into typed exceptions. The CLI presents the failure for a person or emits the same contract as JSON for an agent.

{
  "error": "Authentication required. Provide an API Key or session token.",
  "code": "AUTHENTICATION_REQUIRED",
  "request_id": "req_123",
  "retryable": false,
  "details": {}
}

Failures use error, never a success-shaped message field. code, request_id, retryable, and details are stable machine-readable fields. Details must not contain stack traces, secrets, or internal identifiers.

Status code decisions

StatusMeaningDecision
400Malformed or invalid request.Correct input. Do not retry unchanged input.
401Credential missing, invalid, or expired.Resolve the right credential source. Do not keep retrying the same secret.
403Credential is valid but policy, role, consent, or capability denies the operation.Ask for the required account action or use a permitted route.
404Resource or route is unavailable to the caller.Verify the target and resource scope.
409Conflict, duplicate, or idempotency mismatch.Read the response and reconcile the original logical operation.
429Rate or usage limit.Back off and follow the retry hint.
501The route is known, but the requested capability is not released in the current contract.Do not retry unchanged. Use the documented available path or wait for a versioned release.
5xxService or upstream failure.Retry only when the operation is safe and the response is retryable.

Retry policy

Use bounded exponential backoff with jitter for transient failures. Respect Retry-After and any SDK retry metadata. Do not retry authentication, validation, consent, or permission failures until the underlying condition changes.

for attempt in range(3):
    try:
        response = client.memory.write(text, idempotency_key="event-42")
        break
    except (APITimeoutError, APIConnectionError):
        sleep(backoff_with_jitter(attempt))
else:
    raise RuntimeError("Mpalo request did not become reachable")

Idempotency

An idempotency key identifies one logical write, not one network attempt. Generate it from your event identity, store it with your application event, and reuse it after timeouts. A replay should return the original outcome or a clear conflict, never create an accidental duplicate.

Do not reuse keys across events.

A key collision can make a new event look like a replay. Use a namespace or application identifier in the key when multiple producers share a storage connection.

Storage capability failures

Mind Platform can represent managed and BYO storage connections before their data-plane adapters are released. The current memory runtime accepts only an active Palo Managed Memory connection. If a key is attached to an active connection for another provider, the API returns MEMORY_STORAGE_PROVIDER_UNAVAILABLE with HTTP 409 before it persists, retrieves, deletes, meters, bills, or sends data to that provider.

{
  "error": "The memory storage attached to this API key is configured but its provider adapter is not available for memory operations yet.",
  "code": "MEMORY_STORAGE_PROVIDER_UNAVAILABLE",
  "retryable": false,
  "details": {
    "provider": "pinecone",
    "next": "Attach Palo Managed Memory, or wait for the BYO provider adapter to be released."
  }
}

Troubleshooting sequence

  1. Keep the request ID, target, contract version, and timestamp.
  2. Run palo auth or inspect the SDK credential source without exposing the secret.
  3. Run palo infra health --json and palo infra capabilities --json.
  4. Check storage attachment, consent, role, rate limits, and the selected profile.
  5. Compare events and usage for the same time window.

If the result is still unexplained, provide the request ID and redacted JSON output to support. Do not provide the API key, session token, raw private memory, or an unredacted export.