Error Codes

The Repo Cat API uses standard HTTP status codes and returns structured JSON error responses to help diagnose issues.

Overview

All API errors return a JSON response with the following structure:

{
  "success": false,
  "error": "Human-readable error message describing the issue"
}

The HTTP status code indicates the category of the error, while the error field provides a specific message.

Status Codes

Status Code	Name	Description
200	OK	The request was successful
400	Bad Request	Invalid request parameters (e.g., missing required fields)
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions or scan limit exceeded (daily or monthly)
404	Not Found	Resource not found (repository or scan ID)
429	Too Many Requests	Rate limit exceeded — wait before making more requests
500	Internal Server Error	An unexpected error occurred on the server

Error Codes

400 — Bad Request

Returned when the request is malformed or missing required parameters.

{
  "success": false,
  "error": "Missing required parameter: repo"
}

Common causes:

Missing repo or level query parameters
Invalid scan level (must be "basic", "standard", or "deep")
Invalid repository format (must be "owner/repo")
Malformed JSON in request body

401 — Unauthorized

Returned when the API key is missing, invalid, or expired.

{
  "success": false,
  "error": "Invalid or missing API key"
}

Common causes:

No X-API-Key header provided
Invalid or revoked API key
API key does not match any key in the system

Generate a new API key from your dashboard if you need to replace your key.

403 — Forbidden

Returned when the authenticated user lacks permission or has exceeded scan limits.

{
  "success": false,
  "error": "Daily scan limit reached"
}

Common causes:

Daily or monthly scan limit reached for the requested level
Scan level not available on current plan (e.g., Deep on Free tier)

404 — Not Found

Returned when the requested resource does not exist.

{
  "success": false,
  "error": "Repository not found"
}

Common causes:

Repository does not exist on GitHub
Repository is private (not accessible)
Scan ID does not exist or belongs to another user

429 — Too Many Requests

Returned when the rate limit is exceeded. The rate limit applies to all API requests per minute.

{
  "success": false,
  "error": "Rate limit exceeded. Please wait before making additional requests."
}

Resolution:

Wait one minute before making additional requests
Reduce request frequency to stay within the rate limit
Rate limits apply equally to all users regardless of tier

500 — Internal Server Error

Returned when the server encounters an unexpected condition.

{
  "success": false,
  "error": "An unexpected error occurred"
}

Resolution:

Retry the request after a short delay
If the issue persists, contact support

Troubleshooting

My scan is stuck or timing out

Try cancelling the scan and restarting it. Deep scans can take several minutes for large repositories. If a scan exceeds 5 minutes without progress, check your scan limits and repository accessibility.

I'm getting authentication errors

Verify your API key is correct and included in the X-API-Keyheader. Make sure you're not using a placeholder value and that the key is properly copied from your dashboard.

Getting rate limited frequently

Space out your requests to stay within the per-minute rate limit. This limit applies to all users equally to ensure service availability.

Repository not found

Ensure the repository exists on GitHub and is publicly accessible. Private repositories are not supported. Verify the format is "owner/repo" (e.g., "$facebook/react").