Errors and limits

Gazebo REST endpoints return JSON. Exact fields vary by resource, but HTTP status codes have consistent meanings.

Status codes

Status	Meaning
200 OK	Request completed
201 Created	Resource created
400 Bad Request	Invalid input
401 Unauthorized	Token missing, malformed, expired, revoked, or invalid
403 Forbidden	Token is valid but is not permitted to perform the operation
404 Not Found	Resource does not exist or does not belong to the authenticated account
429 Too Many Requests	Request rate exceeded
500 Internal Server Error	Unexpected server failure

Some account administration errors use a compact body:

{ "error": "Agent not found" }

Agent credential denials include structured context:

{
  "status": "denied",
  "service": "stripe",
  "reason": "This agent does not have permission to access stripe credentials.",
  "next_action": "Enable service access for this agent at gazebohq.com/agents"
}

Do not branch solely on error text. Use the HTTP status and stable structured fields where available.

Pagination and limits

Agent and service collection endpoints currently return JSON arrays. Audit events use cursor pagination:

• limit accepts 1 to 200 and defaults to 50.
• nextCursor is an opaque continuation cursor.
• hasMore indicates whether another page is available.
• Keep all filters unchanged when requesting the next cursor.

Endpoints that do not document filters, cursors, or page parameters do not support them.

Compatibility

The endpoints in this REST API reference are Gazebo's supported external contract. Additive response fields may be introduced over time, so clients should ignore fields they do not recognize.

Dashboard-only /api/v1 endpoints are not covered by this compatibility commitment.