Sorry, your browser does not support inline SVG.

Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen, and mostly they will be yours, not ours. Let's look at the error shapes you might encounter.

MCP tool calls that fail return an error result whose text is a JSON envelope: success: false, the underlying HTTP status, a human-readable message, and — for validation failures — an errors object keyed by field. Many tools also include a next_step hint telling the agent how to recover. Direct HTTP requests signal failure with the status code alone.

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting Stellify support.

Status codes

Here is a list of the different categories of status codes returned by the Stellify API. Use these to understand if a request was successful.

  • Name
    2xx
    Description

    A 2xx status code indicates a successful response.

  • Name
    4xx
    Description

    A 4xx status code indicates a client error — this means it's a you problem.

  • Name
    5xx
    Description

    A 5xx status code indicates a server error — you won't be seeing these.

Error types

Whenever a tool call is unsuccessful, the error envelope tells you what went wrong and — via message and any field-level errors — how to fix it. Most of the error messages are pretty helpful and actionable.

These are the fields of the error envelope.

  • Name
    success
    Description

    Always false on an error result.

  • Name
    status
    Description

    The underlying HTTP status code — 422 for validation failures, 404 for a missing unit, 403 when the token lacks permission.

  • Name
    message
    Description

    A human-readable explanation of what went wrong.

  • Name
    errors
    Description

    For validation failures, an object keyed by field with the specific rule messages; otherwise null.

Error response

{
  "success": false,
  "status": 422,
  "message": "The given data was invalid.",
  "errors": {
    "path": ["The path field is required."]
  }
}