Error Handling

How to handle API errors gracefully

On this page

Error Handling

The Blitz Rocket API uses standard HTTP status codes and returns consistent error response bodies.

HTTP Status Codes

Status CodeMeaning
200OK — Request succeeded
201Created — Resource created successfully
400Bad Request — Invalid parameters or missing required fields
401Unauthorized — Missing or invalid API key
403Forbidden — Insufficient permissions (e.g., public key on private endpoint)
404Not Found — Resource does not exist
429Too Many Requests — Rate limit exceeded
500Internal Server Error — Loading... on our end

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "error": "A human-readable description of the error"
}

Common Errors

Missing API Key

// Status: 401
{
  "success": false,
  "error": "Missing or invalid API key"
}

Private Key Required

// Status: 403
{
  "success": false,
  "error": "This endpoint requires a private API key"
}

Resource Not Found

// Status: 404
{
  "success": false,
  "error": "Contest not found"
}

Validation Error

// Status: 400
{
  "success": false,
  "error": "Either email or phone is required"
}

Handling Errors in Code

async function makeApiRequest(endpoint) {
  const response = await fetch(`https://blitzrocket.com/api/v1${endpoint}`, {
    headers: { "x-api-key": process.env.BLITZROCKET_API_KEY },
  });

  const data = await response.json();

  if (!data.success) {
    switch (response.status) {
      case 401:
        throw new Error("Invalid API key. Check your credentials.");
      case 403:
        throw new Error("Insufficient permissions. Use a private API key.");
      case 404:
        throw new Error(`Resource not found: ${data.error}`);
      case 429:
        throw new Error("Rate limited. Retry with backoff.");
      default:
        throw new Error(`API error: ${data.error}`);
    }
  }

  return data.data;
}

import requests
import os

def make_api_request(endpoint):
    response = requests.get(
        f"https://blitzrocket.com/api/v1{endpoint}",
        headers={"x-api-key": os.environ["BLITZROCKET_API_KEY"]}
    )

    data = response.json()

    if not data.get("success"):
        status = response.status_code
        error = data.get("error", "Unknown error")

        if status == 401:
            raise Exception("Invalid API key. Check your credentials.")
        elif status == 403:
            raise Exception("Insufficient permissions. Use a private key.")
        elif status == 404:
            raise Exception(f"Resource not found: {error}")
        elif status == 429:
            raise Exception("Rate limited. Retry with backoff.")
        else:
            raise Exception(f"API error: {error}")

    return data["data"]