Error Handling

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

HTTP Status Codes

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

Error Response Format

All error responses follow this structure:

json

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

Common Errors

Missing API Key

json

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

Private Key Required

json

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

Resource Not Found

json

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

Validation Error

json

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

Handling Errors in Code

javascript

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;
}