Error Codes

All Pie API error responses follow a standard format:

{
  "success": false,
  "status": 401,
  "message": "Human-readable error description",
  "data": null
}

Authentication Errors

Status	Message	Cause	Resolution
401	`API key is required`	No `X-API-Key` or `Authorization` header provided	Add your API key header: `X-API-Key: YOUR_KEY`
401	`Invalid API key`	API key not found or revoked	Regenerate your API key in Settings > API Keys
401	`Authorization header is required`	Endpoint requires auth but no header provided	Add `Authorization: Bearer <token>` header
401	`Invalid authorization header format`	`Authorization` header doesn’t follow `Bearer <token>` format	Use format: `Authorization: Bearer YOUR_TOKEN`
401	`Invalid Firebase ID token`	Firebase token expired, malformed, or revoked	Refresh your Firebase session token
401	`X-App-ID header is required`	Bearer auth used without specifying target app	Add `X-App-ID: YOUR_APP_ID` header
401	`User does not have access to this app`	Authenticated user isn’t in the app’s permission list	Contact your app admin to grant access

Authorization Errors

Status	Message	Cause	Resolution
403	`Only admin users can switch apps`	Non-admin user tried to use `X-App-ID` header override with API Key auth	Use the API key associated with the target app, or request admin role

Client Errors

Status	Message	Cause	Resolution
400	`Invalid request body`	Request body is not valid JSON or doesn’t match expected schema	Check your JSON syntax and required fields
400	`<field_name> is required`	A required field is missing from the request body	Include the specified field in your request
400	`At least one <item> is required`	Bulk operation called with an empty array	Provide at least one item in the array
400	`X-App-ID header required for scheduler requests`	Scheduler auth used without specifying target app	Add `X-App-ID` header for scheduler requests
404	`<resource> not found`	The requested resource (test case, issue, run, etc.) doesn’t exist	Verify the ID exists. Use the corresponding GET endpoint to list available resources
404	`Endpoint not found`	Invalid URL path	Check the API endpoint URL against the API reference
404	`No runs found for this app`	App has no test runs yet	Create a run first using `POST /v1/runs` or `POST /v1/discovery`
405	`Method not allowed`	HTTP method not supported for this endpoint	Check allowed methods in the API reference
409	`User already has an app`	User tried to create a second app (one-app-per-user limit)	Use `GET /v1/apps` to get your existing app
413	`File too large`	Uploaded build file exceeds the 2GB limit	Reduce file size or contact support for larger builds

Server Errors

Status	Message	Cause	Resolution
500	`Failed to fetch <resource>`	Database read failure	Retry the request. If persistent, check service status
500	`Failed to create <resource>`	Database write failure	Retry the request. Verify your request body is valid
500	`Failed to update <resource>`	Database update failure	Retry the request
500	`Storage client not initialized`	Internal storage service unavailable	Retry after a few seconds. Contact support if persistent
501	`Not implemented`	Endpoint or feature not yet available	Check the API reference for available endpoints

MCP Server Errors

When using the MCP server (https://mcp.pie.inc), tool call errors are returned as MCP protocol error responses:

Error	Cause	Resolution
`Invalid API key`	MCP request sent without valid API key	Check your MCP config includes the correct `X-API-Key` header or `api_key` query parameter
`App not found`	API key not associated with any app	Verify the API key was created for the correct app
`Tool not found`	Called a tool name that doesn’t exist	Check the MCP Tool Reference for valid tool names

Best Practices

Retry strategy: For 500-level errors, retry with exponential backoff (1s, 2s, 4s). Do not retry 400-level errors - fix the request first.

Error handling in code:

response = requests.get("https://api.pie.inc/v1/test-cases",
    headers={"X-API-Key": api_key})

if response.status_code == 200:
    data = response.json()["data"]
elif response.status_code == 401:
    # Re-authenticate
elif response.status_code >= 500:
    # Retry with backoff
else:
    error_msg = response.json()["message"]
    # Handle specific error

Authentication Supported Technologies