Errors

ProteinIQ API errors use a consistent JSON envelope. Clients should branch on error.code, not on the human-readable message.

Error envelope

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request data",
    "resolution": "Correct the request using the OpenAPI contract and error.details when present, then retry.",
    "details": {}
  }
}

The resolution field gives a short next action for the error code. The details field is included only when the route has structured details to return.

Common error codes

These codes cover shared API failures. Workflow and other routes can return additional operation-specific codes; read resolution and details when present.

Handling errors

• Retry rate_limited: Respect Retry-After and the rate-limit reset headers when present.
• Retry transient internal_error responses carefully: Use Idempotency-Key when retrying job submissions.
• Do not retry validation_error unchanged: Inspect the request shape, tool input contract, and field names.
• Rebuild rejected job inputs: Follow the tool input model. Each entry needs id, slotId, kind, format, and source, plus content or a supported saved-file reference. Mixed current and retired fields are rejected.
• Treat not_found as workspace-scoped: A job outside the API key workspace returns not_found.
• Handle job_not_completed by waiting: Poll status or use the events endpoint before fetching results again. When Retry-After is present, wait that many seconds before retrying the result endpoint.
• Use resolution for the next action: Display or log the field when an automated client cannot recover without changing the request or workspace state.

Inspect an error

This read-only example checks the response before using account data:

const response = await fetch("https://proteiniq.io/api/v1/account", {
  headers: {
    Authorization: `Bearer ${process.env.PROTEINIQ_API_KEY}`,
  },
});
const payload = await response.json();
if (!response.ok) {
  const { code, message, resolution, details } = payload.error;
  console.error({ code, message, resolution, details });
  if (code === "rate_limited") {
    console.error("Retry-After:", response.headers.get("Retry-After"));
  }
  throw new Error(`${code}: ${message}`);
}
console.log(payload.workspace);

Do not log the API key or private request contents when reporting an error. For an uncertain job submission, retain its exact payload and idempotency key before retrying.