Error Handling

All Renovatr API errors follow a consistent format.

Error Response Format

{
  "error": "Human-readable error message",
  "details": {}
}

The details field is optional and typically present for validation errors.

HTTP Status Codes

Status	Meaning
200	Success
201	Created (new resource)
400	Bad request — invalid input or validation failure
401	Unauthorized — missing or invalid credentials
403	Forbidden — valid credentials but insufficient permissions
404	Not found — resource doesn't exist or you don't have access
500	Internal server error

Validation Errors

When request body validation fails (via Zod schemas), the response includes structured details:

{
  "error": "Validation failed",
  "details": [
    {
      "path": ["title"],
      "message": "Required"
    },
    {
      "path": ["estimatedCost"],
      "message": "Expected number, received string"
    }
  ]
}

Common Errors

Missing API Key

401 — { "error": "Unauthorized" }

Ensure you're passing the X-API-KEY header.

Wrong Project

403 — { "error": "API key is not authorized for this project" }

API keys are project-scoped. You can only access the project the key was created for.

Insufficient Permissions

403 — { "error": "Forbidden: insufficient permissions" }

Your API key doesn't have the required permission flag. Check your key's permissions in project settings.

Resource Not Found

404 — { "error": "Not found" }

The resource ID doesn't exist, or you don't have permission to view it.

Best Practices

• Always check the HTTP status code before parsing the response body
• Handle 401 by prompting for a new API key
• Handle 403 by checking your key's permission scope
• Log the full error response for debugging
• For 400 errors, inspect the details array to identify which fields need correction