About Solutions integrations Support Login Get Started

Developer Documentation · Safe Failure

Integration Errors & Safe Failure Behaviour

MyOpsAgent integrations should fail in a way that a calling system can recognise and handle. Exact error codes may vary by module or API version, but integrations should distinguish invalid input, authentication or permission failures, conflicts, usage limits, dependency failures and unexpected server errors.

1. Structured Error Responses

Where an API returns JSON, clients should expect a machine-readable status together with a human description and, where available, a correlation identifier.

Illustrative error response
{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "The request could not be authorised.",
  "correlation_id": "example-correlation-id"
}

Do not build client logic around the wording of message. Use the documented status or error code for the specific endpoint.

2. Common Error Categories

INVALID_REQUEST

Required data is missing, malformed or outside the contract accepted by the operation.

UNAUTHORIZED

The request cannot be associated with valid authentication for the requested integration.

FORBIDDEN

The identity or organisation is authenticated but is not permitted to perform the requested operation.

NOT_FOUND

The requested resource is not available within the permitted organisation scope.

CONFLICT

The request conflicts with current business state, a duplicate operation or another controlled workflow.

RATE_LIMITED / USAGE_LIMIT

The request exceeds an applicable rate or plan limit. Clients should respect retry guidance where provided.

DEPENDENCY_UNAVAILABLE

A connected service or required dependency is temporarily unavailable.

INTERNAL_ERROR

An unexpected platform error prevented the request from completing.

3. HTTP Behaviour

Where applicable, integrations should use standard HTTP semantics:

  • 400 — invalid request
  • 401 — authentication required or invalid
  • 403 — authenticated but not permitted
  • 404 — resource not found in the allowed scope
  • 409 — state conflict
  • 429 — rate or usage limit
  • 5xx — server or dependency failure

The endpoint-specific contract remains authoritative where it defines different behaviour.

4. Controlled Workflow Failure

A controlled operational workflow should not convert an uncertain or invalid state into an authorised action merely to produce an answer. Depending on the workflow, MyOpsAgent can instead:

  • request clarification;
  • report that no valid option satisfies the constraints;
  • leave a decision awaiting approval;
  • decline an action that exceeds permission;
  • invalidate and recalculate a decision when the underlying state changes; or
  • record that execution or verification failed.

5. Correlation & Troubleshooting

Keep correlation, request, decision or execution identifiers returned by the platform. They are more useful for support and audit than copying sensitive payloads into application logs.

6. Client Guidance

  • Do not retry write operations blindly.
  • Use idempotency or duplicate protection where the integration contract provides it.
  • Do not broaden permissions to work around a 403.
  • Do not assume an explanatory chat response means an action completed.
  • Surface failures clearly to the user when human intervention is required.