Skip to content

Reference

Errors should be actionable

Every failure has a transport status and a stable human-readable error field. 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.",
  "details": {"request_id": "req_123"}
}

Failures use error, never a success-shaped message field. Details are optional and 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.
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.

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.