Responses and Errors

Maito REST responses use a JSON envelope.

Success Envelope

A successful response has ok: true and a data value.

{
  "ok": true,
  "data": {}
}

data can be an object, array, string, number, boolean, or null, depending on the endpoint.

An error response has ok: false and an error object.

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request."
  }
}

details may be included for validation issues or structured domain context:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "details": []
  }
}

Status	Meaning
`400`	The request body, query, or path parameter is malformed.
`401`	The API key is missing, invalid, or expired.
`403`	The key is valid, but the caller cannot access the requested resource or capability.
`404`	The resource was not found.
`409`	The request conflicts with current state.
`422`	The request was readable but failed validation or domain rules.
`429`	The client is sending requests too quickly.
`500`	Server error or server misconfiguration.

Code	Meaning
`UNAUTHORIZED`	Authentication is required or invalid.
`VALIDATION_ERROR`	Request input failed validation.
`NOT_FOUND`	The requested resource does not exist or is not visible to the caller.
`CONFLICT`	The operation conflicts with current resource state.
`SERVER_MISCONFIGURED`	The server is missing required configuration.

Exact domain error codes can vary by endpoint. Clients should branch on HTTP status first, then use error.code for product-specific handling.

Status	Retry?
`400`	No. Fix the request.
`401`	No. Create or provide a valid API key.
`403`	No. Check permissions or account access.
`404`	Usually no. Verify the resource ID or path.
`409`	Retry only after changing the request or resource state.
`422`	No. Fix the request data.
`429`	Yes, after waiting.
`500`	Yes, with exponential backoff.