---
title: "Errors — JustTCG API"
description: "JustTCG API error reference: HTTP status codes, the v1 error shape with codes like INVALID_API_KEY and RATE_LIMIT_EXCEEDED, and v2 problem+json errors."
url: https://justtcg.com/docs/errors
markdown_url: https://justtcg.com/docs/errors.md
---

# Errors

Standard HTTP status codes and consistent error response shapes to help you identify and resolve issues quickly.

Current production API. Errors return a flat { error, code } object.

## HTTP status codes

| Status | Label | When it happens |
| --- | --- | --- |
| 400 | Bad Request | The request was malformed or missing required parameters. |
| 401 | Unauthorized | Missing or invalid API key. |
| 403 | Forbidden | Valid API key, but its plan is not active on your account (SUBSCRIPTION\_REQUIRED). details.reactivate\_url resubscribes to that plan, after which the same key works again. |
| 404 | Not Found | The requested resource could not be found. |
| 429 | Too Many Requests | Rate limit exceeded. Slow down your requests. |
| 500 | Server Error | An unexpected error occurred on the server. |

## Error response shape

Errors include an `error` message and a machine-readable `code`.

```json
{
  "error": "Invalid game parameter. Must be one of: magic-the-gathering, mtg, pokemon, yugioh, age-of-sigmar, warhammer-40000, union-arena, flesh-and-blood-tcg, disney-lorcana, digimon-card-game, one-piece-card-game",
  "code": "INVALID_REQUEST"
}
```

## Error codes

| Code | Description |
| --- | --- |
| MISSING\_API\_KEY | The API key is missing from the request. |
| INVALID\_API\_KEY | The API key provided is invalid or has been revoked. |
| INVALID\_REQUEST | A required parameter is missing or invalid. Check the error message for details. |
| RATE\_LIMIT\_EXCEEDED | You have exceeded your per-minute rate limit. Slow down or upgrade your plan. |
| DAILY\_LIMIT\_EXCEEDED | You have exceeded your daily usage limit. Wait until reset (00:00 UTC) or upgrade. |
| REQUEST\_LIMIT\_EXCEEDED | You have exceeded your monthly usage limit. Wait for the next billing cycle or upgrade. |

**Pro tip:** Implement retry logic with exponential backoff for transient server errors (500) and rate limiting (429).