Pagination and errors

Pagination is endpoint-specific. If a list supports cursors, request a bounded limit value. Pass the returned nextCursor back as after. The cursor response usually contains items, nextCursor, and hasMore. Do not assume that every list supports cursor pagination. Inbox uses its own cursor form. Activity sessions use numbered pages. Some resource lists have no pagination. Check the generated reference for the route that you call.

Request-schema failures use the 400 VALIDATION_ERROR envelope. Scope failures use 403 INSUFFICIENT_SCOPE. Unexpected handler or middleware failures use 500 INTERNAL_ERROR. Before you use a response, parse the shared { success, data, error } structure. Keep the error code in your logs. This helps operators distinguish malformed requests from authorization mistakes.

Retry only failures that are safe for the operation. You can often retry reads and idempotent updates after a transient error. Creations, sends, and other externally visible actions need an idempotency strategy in your own service. Do not retry validation or scope errors without changes. Fix the input or the relevant configuration first.

Repeated write requests

AgentStack also removes exact duplicate write requests on the server. It hashes the actor, the operation, and the validated input. An identical repeat inside the window returns the result of the first call. That response carries deduped: true next to data, in the same { success, data, error } envelope. This key is not in the generated reference, so do not write code that fails when it appears.

The window is 60 seconds for a write or a delete. For a customer-facing send, the window is 15 minutes. Today the only such send is POST /inbox/tickets/{ticketId}/reply.

Two error codes come from this check:

• OPERATION_IN_PROGRESS — an identical call is still running. Read the current state before you retry.
• DEDUPE_CLAIM_FAILED — AgentStack could not confirm whether the send already happened, so it refused the call instead of risking a second message.

Both codes arrive with the default error status of the endpoint that you called. Match on the error code, not on the status.

Do not treat this check as your own idempotency strategy. It hashes the input after validation, so an omitted field and a field that you send equal to its default count as the same call. It does not cover a repeat after the window, a changed input, or a different actor. AgentStack can also skip the check for a write or a delete when its store is unavailable. Keep your own idempotency key for anything that must happen once.