---
title: "Errors"
description: "The error shape every endpoint returns and the standard error codes."
canonical_url: "https://developers.rankability.com/guides/errors"
section: "Get started"
last_updated: 2026-11-14
---

# Errors

The error shape every endpoint returns and the standard error codes.

## Error format

All errors follow a consistent structure:

```json
{
  "error": {
    "code": "invalid_input",
    "message": "Human-readable description of what went wrong",
    "details": {}
  }
}
```

### Standard error codes

| HTTP | Code | Description |
|---|---|---|
| 400 | `invalid_input` | Request body validation failed |
| 400 | `invalid_operation` | Operation not valid for current state |
| 401 | `unauthorized` | Missing, invalid, expired, or revoked API key |
| 403 | `forbidden` | Key lacks required scopes |
| 404 | `not_found` | Resource not found or doesn't belong to your org |
| 409 | `conflict` | Resource state conflict (e.g., job already in progress) |
| 409 | `already_approved` | Brief already approved |
| 409 | `not_ready` | Artifacts not yet available |
| 402 | `insufficient_credits` | Not enough credits to run this job |
| 402 | `copywriter_allowance_exhausted` | Core completed-outcome allowance has been used for the current period |
| 403 | `plan_required` | Active subscription required |
| 403 | `plan_limit_exceeded` | Plan limit reached (e.g., max tracking projects) |
| 429 | `rate_limit_exceeded` | Too many requests |
| 429 | `usage_limit_reached` | Pooled on-demand usage is paused until `retry_at`; scheduled work remains protected |
| 429 | `capacity_reached` | Tracker is too busy to start a scan; retry after `Retry-After` |
| 429 | `concurrency_limit_reached` | Your organization already has the maximum number of these jobs running; retry when one finishes |
| 410 | `credit_balance_retired` | This pooled account uses `/usage`, not a credit balance |
| 503 | `service_unavailable` | Queue service unavailable |
