Lightspark
Lightspark

Errors

SDKs may throw errors which contain an error code and message.

GraphQL Status Codes

If you're not using an SDK and are manually querying with GraphQL, you may encounter the following status codes.

Status 200 OK

GraphQL HTTP status codes are different from REST API status codes. Most importantly, the GraphQL API can return a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST. As long as GraphQL can process the request, it will return a 200 OK code with more details about the success (or errors).
A typical GraphQL response will be:
{
  data: {/* a JSON object that has the shape of the requested data */},
  errors: [/* an optional array of all the errors that happened during the execution of the request */],
}
In GraphQL, each field is resolved independently, so it will try to return as much information as possible (even partial data) and let the client decide if it should be displayed or not.
Sample query:
query Test($node_id: ID!) {
  entity(id: $node_id) {
    ... on LightsparkNodeWithOSKLND {
      display_name
      grpc_hostname
    }
  }
}
Sample response:
{
  data: { entity: { display_name: "My amazing node", grpc_hostname: null } },
  errors: [
    {
      message: "Couldn’t reach the node, something went wrong.",
      extensions: {
        error_name: "NodeOfflineException",
      },
      path: [
        "entity",
        "grpc_hostname"
      ],
    },
  ],
}
In the example above, we were unable to resolve the grpc_hostname field on the LightsparkNode but we got the display_name. The client can choose to render a "degraded" experience instead of failing the entire request.
The error object returned will expose an error.extensions.error_name, which is a key that can be used to identify the type of error.
Examples include: UnauthorizedException, InvalidLightsparkIDException, or InvalidNodePasswordException. The documentation for those codes can be found in this page as part of the queries/mutations descriptions.

Status 4xx and 5xx

These errors occur before the request hits the Lightspark API. They may be related to network issues, account issues, malformed requests, or Lightspark internal issues. Some examples below:
CodeDescription
400 Bad RequestYou may have malformed your GraphQL request (for example, forgot to include the query field in the payload).
401 UnauthorizedThe token/token_id pair is not valid and we cannot authenticate your account in the request.
402 Payment RequiredYour account might be on hold because of billing issues, or you are trying to use a feature that is not in your plan.
403 ForbiddenYour account might be on hold because of suspicious activity.
429 Too Many RequestsYour account sent too many requests in a short period of time and was rate limited.
5xx Server ErrorAn error occurred on the Lightspark side, we will investigate as soon as possible.