Errors

PIE V2 uses a small JSON error envelope for common API errors.

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

The message is meant for operators and developers. Do not parse it for control flow; use the HTTP status and the operation contract.

Status codes

Status	Meaning
400 Bad Request	The request is malformed, path parameters are invalid, or syntactic validation failed.
401 Unauthorized	The bearer token is missing, expired, invalid, or rejected by API authorization.
403 Forbidden	The token is valid but lacks the required operation permission or tenant access.
404 Not Found	The requested resource was not found in the addressed scope.
422 Unprocessable Entity	The request is syntactically valid but semantically invalid, such as no model assignment, inactive domain, or feature-contract mismatch.
5xx	Server or integration failure. Retry only when the operation is safe to retry.

Route-specific error bodies

Most routes return the envelope above. Some operations document additional response schemas for specific failure modes — for example, a different JSON shape for the same HTTP status on one route. Use the API reference for the operation you are calling; do not assume every 4xx/5xx on that route matches the default envelope.

Job failures vs API errors

An API request can succeed while the job it created later fails. For model work, always poll the job and check its status, output, and error fields.

API errors describe whether the request was accepted. Job errors describe what happened during model execution.