Troubleshooting Common API Errors

Every API error response is JSON with an HTTP status and a human-readable message. Here's what the common codes mean and how to fix them.

Quick Reference#

400 — Bad Request#

Malformed request or missing required fields. Validate JSON syntax, match the documented field names and types, and don't send a body with GET requests.

401 — Unauthorized#

Token is missing, invalid, or revoked. Check:

• The Authorization header uses the Bearer prefix (not Token or Basic)
• The token isn't cut off or padded with whitespace
• The token hasn't been deleted at versedb.com/user/api-tokens

Test with GET /api/user — if that 401s, the token is the problem.

402 — Payment Required#

You're calling a PRO-only endpoint without a PRO subscription. The response includes an upgrade URL. Either upgrade at versedb.com/subscription or switch to a free-tier endpoint.

403 — Forbidden#

You're authenticated but your token doesn't have the required scope, or you're trying to access someone else's private data. Available scopes are read:public, read:user, lists:follow, lists:pulllist, lists:collection, lists:read, and lists:user_lists. Create a new token with the right scope if needed.

404 — Not Found#

The resource doesn't exist. The API uses numeric IDs, not slugs — GET /api/series/123, not GET /api/series/amazing-spider-man-2018. Use ?q= on list endpoints to find IDs by name.

422 — Unprocessable Entity#

Your request is well-formed but failed validation. The response includes a per-field errors object — read it to see which field failed and why.

{
  "message": "The given data was invalid.",
  "errors": {
    "condition": ["The selected condition is invalid."]
  }
}

Common validation constraints — condition uses CGC-style grade values (MT, NM, NM-, VF+, VF, F, VG, G, FR, PR, plus intermediates); grade scores are 0.5–10.0. Check the field-specific docs at /api/docs for exact allowed values.

429 — Too Many Requests#

Rate limit hit. Response headers include Retry-After (seconds to wait) and X-RateLimit-Reset (Unix timestamp). Wait the full interval — don't retry immediately.

See Understanding API Rate Limits for limits and backoff strategies.

500 / 503 — Server Errors#

Server-side issue. Retry with exponential backoff (1s, 2s, 4s). If it persists, email support with the request URL, timestamp, and response body.

Debugging#

Always log the full response body — the message and errors fields usually tell you exactly what's wrong.

curl -v -H "Authorization: Bearer YOUR_TOKEN" https://versedb.com/api/user