Error Handling

Learn how to handle errors returned by the GuardCrow API.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests.

Status	Name	Description
200	OK	Request successful
400	Bad Request	Invalid request body or missing required fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key doesn't have access to this resource
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error - please retry

Error Response Format

All error responses follow a consistent JSON format:

error-response.jsonjson

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}

Error Codes

Code	HTTP Status	Description
MISSING_API_KEY	401	X-API-Key header is missing
INVALID_API_KEY	401	API key is invalid or revoked
MISSING_CONTENT	400	content field is required
CONTENT_TOO_LONG	400	Content exceeds 10,000 characters
INVALID_JSON	400	Request body is not valid JSON
RATE_LIMIT_EXCEEDED	429	Too many requests, slow down
INTERNAL_ERROR	500	Server error, please retry

Handling Errors in Code

error-handling.tstypescript

async function analyzeContent(content: string) {
  const response = await fetch("https://api.guardcrow.com/v1/analyze", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.GUARDCROW_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ content }),
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.error.code) {
      case "RATE_LIMIT_EXCEEDED":
        // Wait and retry
        await sleep(1000);
        return analyzeContent(content);

      case "INVALID_API_KEY":
        throw new Error("Check your API key configuration");

      default:
        throw new Error(error.error.message);
    }
  }

  return response.json();
}

Retry Strategy

For transient errors (429, 500), we recommend implementing exponential backoff:

Wait 1 second, then retry
If it fails again, wait 2 seconds
Continue doubling wait time up to 32 seconds
After 5 retries, fail permanently

Tip: For 429 errors, check the X-RateLimit-Reset header to know exactly when you can retry.