This page lists each error that the API returns. It tells you what the error means and how to correct it. It also shows which AI hosts can connect to the solver. It gives the setup for each host.
Error responses have this form: {"detail": {"code", "message", "hint"}}. Use the code value in your repair loop. The code is stable across versions.
| HTTP | code | Meaning and correction |
|---|---|---|
| 401 | NO_API_KEY | You sent no key. Add the header Authorization: Bearer <key>. Make a free key at /signup.html. |
| 401 | INVALID_API_KEY | The system does not know the key. Look for wrong characters or spaces. Or make a new key on your account page. |
| 402 | QUOTA_EXCEEDED | This code is for a future solve quota. It is off in the research preview. Thus you do not see it. Everything is free and unlimited now. |
| 429 | RATE_LIMITED | You sent requests faster than the fair-use limit (free plan: 60 solves/minute, 1000/hour per key). Wait the number of seconds in the Retry-After header, then continue. For many problems, use one /v1/batch call. There is no monthly quota — this only limits burst speed. |
| 429 | DEMO_LIMIT | The keyless demo endpoint has an hourly per-address limit. Make a free API key at /signup.html and use /v1/solve. |
| 413 | PROBLEM_TOO_LARGE | The mesh is over the plan's size cap (free plan: 20,000 nodes and 20,000 elements per solve). Coarsen the mesh, split the model, or use analysis: adaptive to refine only where the error is. Your caps: GET /auth/usage. |
| 413 | BATCH_TOO_LARGE | Too many problems in one /v1/batch call (free plan: 20). Split the batch. |
| 404 | JOB_NOT_FOUND | The async job id does not exist for this key. Job ids expire about an hour after they finish. Poll with the same key that submitted the job, and collect results promptly. |
| 409 | JOB_NOT_CANCELLABLE | You tried to cancel a job that already started or finished. Only queued jobs can be cancelled. |
| 429 | TOO_MANY_JOBS | Too many unfinished background jobs on this key (default 10). Poll GET /v1/jobs/{id} to collect finished results or DELETE queued ones. |
| 422 | SINGULAR_STIFFNESS | The structure has too few constraints. It can move as a rigid body. Add supports. A 2D beam needs one rz constraint. |
| 422 | NODE_OUT_OF_RANGE | An element or a support uses a node index that does not exist. Indices start at 0. Compare the index with the nodes list. |
| 422 | INVALID_DOF | A support or a load uses a DOF that the element does not have. An example is rz on a truss. Get the correct dof_names from /capabilities. |
| 422 | MISSING_SECTION_FIELD | A necessary section field is missing. Examples are A, I, and t. See the section for each element in /capabilities. |
| 422 | ZERO_LENGTH_ELEMENT | Two nodes of the element have the same coordinates. Give the element different end nodes. |
| 422 | UNKNOWN_ELEMENT_TYPE | The system does not know the element type. Use a type from element_types in /capabilities. |
Do the results have the wrong magnitude but no error? Check the units. physicsbase uses SI units (Pa, m, N). The field summary.warnings shows probable mistakes. An example is E in GPa. The field summary.verification.balanced must be true.
This table shows how each common AI host connects to the solver. “Tested” means that we did a complete solve and got a result.
| Host | Works | How |
|---|---|---|
| Claude and MCP clients | ✓ | Add the remote MCP server: {"mcpServers":{"physicsbase":{"url":"https://www.physicsbase.dev/mcp"}}} |
| ChatGPT (Custom GPT) | ✓ | Make a GPT. Open Actions. Import https://www.physicsbase.dev/openapi.json. Set the auth to API key (Bearer). |
| Cursor / Windsurf | ✓ | Add the same MCP server URL in the MCP settings of the editor. |
| LangChain / LlamaIndex | ✓ | Load /openapi.json as an OpenAPI toolkit. Set the Bearer key. |
| Any code or agent with HTTP | ✓ | Send POST /v1/solve with the Bearer header. Read /llms.txt first. |
| ChatGPT plain browsing | ✗ | The browse tool is read-only (GET). It can read the docs but it cannot POST. Use a Custom GPT Action. |