Errors

The Cirro API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with Cirro's servers (these are rare).

Error response format

The body of any error response will be a JSON object with a single error key containing a human-readable message:

{ "error": "message" }

HTTP status codes

Authentication errors

Authentication errors return a 401 status code. These occur when the JWT access token is missing, malformed, or expired.

Validation errors

Validation errors return a 400 or 422 status code. A 400 is returned when required parameters are missing or have invalid formats. A 422 is returned when the parameters are well-formed but fail domain-level validation (e.g., a record is invalid or a state transition is not allowed).

Common validation error scenarios:

Resource-specific errors

Users

Gigs

Gig Results

Gig Time Activities

Payouts

Notification Topics

Idempotency

When you include an Idempotency-Key header in a create request and a previous request with the same key has already been processed, the API returns a 208 Already Reported status with the original response body. This is not an error — it indicates the request was already fulfilled.

Handling errors

We recommend writing code that handles errors gracefully. Here are some best practices:

• Check the HTTP status code before parsing the response body.
• Parse the error field from the JSON response to get a human-readable description of what went wrong.
• Retry on 5xx errors with exponential backoff, as these indicate temporary server issues.
• Do not retry 4xx errors without modifying the request, as the same request will produce the same error.
• Use idempotency keys for create requests to safely retry without risking duplicate records.