Error Codes

Error Response Format

All errors follow this format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description of what went wrong"
  }
}

HTTP Status	Code	Description	What to Do
`400`	`bad_request`	Invalid request body, missing fields, or validation error	Check the `message` for specifics. Fix the request and retry.
`401`	`unauthorized`	Missing, invalid, expired, or revoked API key	Check your `Authorization` header format: `Bearer chirpie_sk_...`
`403`	`forbidden`	Valid key but insufficient permissions	Check your plan limits or account status.
`404`	`not_found`	Resource doesn't exist or belongs to another user	Verify the ID. Posts/accounts are scoped to your user.
`429`	`rate_limited`	Monthly quota or burst rate limit exceeded	Wait and retry, or upgrade your plan.
`500`	`internal_error`	Unexpected server error	Retry after a moment. If persistent, contact support.
`502`	`upstream_error`	X/Twitter API returned an error	Often temporary. Scheduled posts auto-retry. For immediate posts, retry after a delay.

{ "error": { "code": "unauthorized", "message": "Invalid API key" } }

The key doesn't match any active key in our database. It may have been revoked or mistyped.

{ "error": { "code": "unauthorized", "message": "API key has been revoked" } }

This key was explicitly revoked. Create a new key from the dashboard or API.

{ "error": { "code": "rate_limited", "message": "Monthly post limit reached (50/50 used)..." } }

You've hit your plan's monthly post quota. Upgrade your plan or wait for the next month.

{ "error": { "code": "not_found", "message": "Account not found or not active" } }

The account_id doesn't exist, belongs to another user, or the X OAuth tokens have expired. Check the accounts list and re-authorize if needed.

{ "error": { "code": "upstream_error", "message": "Failed to post: X API error - Rate limit exceeded" } }

X/Twitter rejected the request. Common causes: rate limits, suspended account, or content policy violation.