Error codes

Every Pie API error response uses the same envelope:

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

An error response has no data field. Some errors also carry an errorId.

Authentication and authorization errors

Status	Message	Cause	Resolution
401	`Authentication required: provide either X-API-Key header or Authorization Bearer token`	No `X-API-Key` header, and no `Authorization` header in the `Bearer <token>` form	Add your API key header: `X-API-Key: YOUR_KEY`
401	`Invalid API key`	API key not found or revoked	Create a new key in Settings > API Keys, then update the place that used the old one. See Create an API key
401	`Invalid Firebase ID token`	The bearer token isn’t a valid or current Pie session token	Sign in to the Pie web app again, or send your API key in `X-API-Key`
401	`X-App-ID header is required`	Bearer auth used without naming the target app. The message continues: `please hit /v1/apps to get the app ids you have access to`	Add an `X-App-ID: YOUR_APP_ID` header. Call `/v1/apps` to list the app IDs you can use
401	`User does not have access to this app`	The signed-in user isn’t in the app’s permission list	Ask someone on the team to invite you. See Invite your team
403	`API key cannot access the requested app`	The API key doesn’t have access to the app the request asked for	Use the API key created for the target app
503	`Authentication service temporarily unavailable`	Pie couldn’t check your credentials	Retry after a few seconds. Contact support if it persists

Client errors

Status	Message	Cause	Resolution
400	`Invalid request body`	Request body isn’t valid JSON or doesn’t match the 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 named field in your request
400	`At least one <item> is required`	A bulk operation was called with an empty array	Provide at least one item in the array
400	`No runs found for this app`	The app has no test runs yet	Create a run first with `POST /v1/runs`
400	`Default is your test library and cannot be started as a run…`	`POST /v1/runs` named Default, the library of tests that sit in no suite, as the suite	Name a test suite, or pass `testCaseIds` to run specific tests
404	`<resource> not found`	The requested resource (test case, issue, run and so on) doesn’t exist	Check the ID. Use the matching GET endpoint to list available resources
404	`Endpoint not found`	Invalid URL path	Check the path against the API reference
405	`Method not allowed`	HTTP method not supported for this endpoint	Check the allowed methods in the API reference
413	`Build file exceeds the <bytes> byte limit`	The uploaded build file is larger than the allowed size	Reduce the build size, or contact support for larger builds
413	`Build upload exceeds the maximum request size`	The upload request is larger than the allowed size	Reduce the build size, or contact support for larger builds

Server errors

Status	Message	Cause	Resolution
500	`Failed to fetch <resource>`	A read failed	Retry the request. If it persists, contact support
500	`Failed to create <resource>`	A write failed	Retry the request. Check that your request body is valid
500	`Failed to update <resource>`	An update failed	Retry the request

MCP server errors

On the MCP server at https://mcp.pie.inc, the two API key errors come back as MCP protocol errors when your client connects. A call to a tool that doesn’t exist comes back as a tool result marked as an error.

Error	Cause	Resolution
`API key required in X-API-Key header`	The request carried no API key	Check that your MCP configuration sends the `X-API-Key` header
`Failed to validate API key: API key not found`	The key you sent isn’t a Pie API key	Check the key, or create a new one. See Create an API key
`Unknown tool: <name>`	The tool name doesn’t exist	Check the tool name against MCP tools

Retry and error handling

Retry 500-level errors with exponential backoff (1 second, 2 seconds, 4 seconds). Don’t retry 400-level errors. Fix the request first.

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
    pass
elif response.status_code >= 500:
    # Retry with backoff
    pass
else:
    error_msg = response.json()["message"]
    # Handle specific error

Last updated on October 27, 2026

Authentication