Guides

Errors

HTTP status codes and GraphQL error codes of the Nipto API, and what to do about each.

An error always comes back as JSON with an errors list. Each error has a message for humans and an extensions.code for your automations. Errors about one field also carry path and locations, and data holds null for that field.

{
  "errors": [
    {
      "message": "Task not found",
      "locations": [{ "line": 1, "column": 12 }],
      "path": ["createActivity"],
      "extensions": { "code": "INTERNAL_SERVER_ERROR" }
    }
  ],
  "data": { "createActivity": null }
}

HTTP status

Problems with the call itself use the HTTP status, so tools like Home Assistant see them as failures:

Status	Code	When	What to do
`200`	none	The call worked, or a field failed for a reason of its own (below)	Read `data`, then check `errors`
`400`	`GRAPHQL_PARSE_FAILED`	The query is not valid GraphQL	Fix the syntax
`400`	`GRAPHQL_VALIDATION_FAILED`	The query asks for a field or argument that does not exist	Compare with the reference
`400`	`BAD_USER_INPUT`	A variable is missing or has the wrong type, or the body is not JSON with a `query`	Fix the variables or the body
`401`	`UNAUTHENTICATED`	No token, an unknown or revoked token, or a token whose owner is no longer in a tribe	Check the token, see Authentication
`403`	`FORBIDDEN`	Premium ended more than 7 days ago	Renew Premium, see Premium
`429`	`TOO_MANY_REQUESTS`	More than 2,000 calls today	Wait for `Retry-After`, see Rate limits

Errors on a field

When the call is fine but a mutation cannot do what it was asked, the status stays 200 and the error is in errors:

Code	Examples
`BAD_USER_INPUT`	`createActivity` without `doers`; a paused member as doer; `limit` below 1; a `repeat` out of bounds; `rotate` without `repeat`
`FORBIDDEN`	`deleteActivity` refused, as the app would: members under parental control cannot delete, and only an admin can refuse an activity waiting for approval
`INTERNAL_SERVER_ERROR`	Other refusals, with a message saying why: `Task not found`, `User not found`, `Date cannot be in the future`, `Date cannot be in the previous weeks`, `Activity cannot be deleted if week is ended`, `Date must be today or in the future`