Error Codes

This guide explains the HTTP error responses you may encounter when using the Cicle Open API.

Error Response Format

All errors follow a consistent format:

{
  "message": "Description of what went wrong"
}

HTTP Status Codes

401 — Unauthorized

The request could not be authenticated.

Common causes:

API key is invalid or not found in the system.

API key has expired.

Bot user associated with the API key no longer exists.

Authorization header is missing or malformed.

How to fix:

Verify your API key is correct and has not been deleted.

Check if the API key has an expiration date that has passed.

Ensure the Authorization header uses the format: Bearer <your_api_key>

402 — Payment Required

The company's subscription is expired or inactive.

Common causes:

Company subscription has expired.

Company subscription is not active.

User quota has been exceeded.

How to fix:

Renew or activate the company subscription.

Contact the company admin to check subscription status.

403 — Forbidden

The request is authenticated but the API key does not have permission to perform this action.

Common causes:

API key does not have the required permission scope for this endpoint.

API key has an empty scopes array ([]), meaning no permissions.

For Company API Keys, the hasApikeyPermission middleware was not included on the route.

How to fix:

Check which scopes the endpoint requires (see the endpoint documentation).

Update the API key to include the required scopes.

Ensure you are using the correct API key type (Company vs User).

400 — Bad Request

The request parameters are invalid or missing.

Common causes:

Required fields are missing from the request body.

Invalid ObjectId format for IDs.

Team does not belong to the company specified in the API key.

Company is not valid.

How to fix:

Check the endpoint documentation for required parameters.

Ensure all IDs are valid MongoDB ObjectId strings (24-character hex strings).

Verify the team belongs to the company bound to your API key.

429 — Too Many Requests

Rate limit exceeded.

Common causes:

Too many requests made within the time window.

API keys have stricter rate limits than user sessions.

How to fix:

Wait before retrying (implement exponential backoff).

Use bulk endpoints to reduce the number of requests.

Cache responses where possible.

See Rate Limiting for details.

500 — Internal Server Error

An unexpected error occurred on the server.

How to fix:

Retry the request after a short delay.

If the problem persists, contact support with the request details.

Error Summary Table

Status	Meaning	Action
400	Bad request / validation error	Check request parameters
401	Authentication failed	Verify API key
402	Subscription expired	Renew company subscription
403	Permission denied	Check API key scopes
404	Resource not found	Verify the resource ID
429	Rate limit exceeded	Wait and retry
500	Server error	Retry or contact support

Error Response Format#

HTTP Status Codes#

401 — Unauthorized#

402 — Payment Required#

403 — Forbidden#

400 — Bad Request#

429 — Too Many Requests#

500 — Internal Server Error#

Error Summary Table#

Error Response Format

HTTP Status Codes

401 — Unauthorized

402 — Payment Required

403 — Forbidden

400 — Bad Request

429 — Too Many Requests

500 — Internal Server Error

Error Summary Table