Skip to main content
All Reminix API errors follow a consistent structure that includes the error details and execution metadata for debugging. Every error response points you to the execution in your dashboard so you can inspect what went wrong.

​
Error response format

{
  "error": {
    "type": "ValidationError",
    "message": "Input field 'prompt' is required"
  },
  "execution": {
    "id": "exec_abc123",
    "url": "https://reminix.com/dashboard/executions/exec_abc123",
    "type": "invoke",
    "status": "failed",
    "duration_ms": 150
  }
}

​
Error fields

​
error.type
string
Error category. Common values: ValidationError, NotFoundError, AuthenticationError, ExecutionError, TimeoutError.
​
error.message
string
Human-readable error description explaining what went wrong.
​
execution.id
string
Unique execution identifier. Use this to look up the execution in the dashboard or API.
​
execution.url
string
Direct link to the execution details in the Reminix dashboard. Includes logs, input/output, and timing information.
​
execution.type
string
The execution type: invoke, chat, or workflow.
​
execution.status
string
Always "failed" for error responses.
​
execution.duration_ms
number
How long the execution took in milliseconds before failing.

​
HTTP status codes

CodeMeaningCommon Causes
400Bad RequestInvalid input, missing required fields, schema validation failure
401UnauthorizedInvalid or missing API key, expired token
404Not FoundAgent doesn’t exist, invalid endpoint, conversation not found
429Too Many RequestsRate limit exceeded
502Bad GatewayRuntime error, agent crashed during execution
504Gateway TimeoutAgent took too long to respond
The request body failed validation. Check that all required fields are present and match the expected types.
{
  "error": {
    "type": "ValidationError",
    "message": "Input field 'prompt' is required"
  }
}
The API key is missing, invalid, or expired. Ensure your Authorization header is set correctly.
{
  "error": {
    "type": "AuthenticationError",
    "message": "Invalid API key"
  }
}
The agent threw an unhandled error during execution. Check the execution URL in the dashboard for stack traces and logs.
{
  "error": {
    "type": "ExecutionError",
    "message": "Agent 'my-agent' threw an error: Connection refused"
  }
}
The agent did not respond within the configured timeout. Consider optimizing the agent or increasing the timeout in your project settings.
{
  "error": {
    "type": "TimeoutError",
    "message": "Agent 'my-agent' timed out after 30000ms"
  }
}

​
Handling errors in the SDK

The SDK throws typed errors that you can catch and inspect. 
import Reminix, { APIError } from "@reminix/sdk"

const client = new Reminix({ apiKey: "your-api-key" })

try {
  const response = await client.agents.invoke("my-agent", {
    input: { prompt: "Hello" },
  })
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status)        // 400, 401, 404, etc.
    console.log(error.message)       // Human-readable message
    console.log(error.execution?.id) // Execution ID for debugging
  }
}

​
Runtime errors

When an agent throws an error during execution, Reminix wraps it and returns a 502 Bad Gateway response. The original error message is included in the response. 
{
  "error": {
    "type": "ExecutionError",
    "message": "Agent 'my-agent' threw an error: Connection refused"
  },
  "execution": {
    "id": "exec_def456",
    "url": "https://reminix.com/dashboard/executions/exec_def456",
    "type": "invoke",
    "status": "failed",
    "duration_ms": 2340
  }
}
Runtime errors may include sensitive information from your agent’s stack trace. In production, consider catching errors in your handler and returning sanitized messages.

​
Retry behavior

The SDK does not automatically retry failed requests. Implement retries in your application code for transient errors (502, 504, 429). 
import Reminix, { APIError } from "@reminix/sdk"

async function invokeWithRetry(
  client: Reminix,
  agent: string,
  input: any,
  maxRetries = 3
) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.agents.invoke(agent, { input })
    } catch (error) {
      if (error instanceof APIError && [502, 504, 429].includes(error.status)) {
        const delay = Math.pow(2, attempt) * 1000
        await new Promise((resolve) => setTimeout(resolve, delay))
        continue
      }
      throw error
    }
  }
  throw new Error(`Failed after ${maxRetries} retries`)
}
Every error response includes an execution.url pointing to the execution details in your dashboard. Use it to inspect logs, input/output, and timing information for debugging.

​
Next steps

Troubleshooting

Common failure modes and how to fix them.

TypeScript: Error Handling

Catch and handle errors from @reminix/sdk.

Python: Error Handling

Catch and handle errors from the Python SDK.

API Reference

Status codes and error shapes for every endpoint.