Error Codes Reference

This page is a comprehensive reference for the error codes returned by the Lumar GraphQL API. Use the extensions.code field in error responses to identify errors programmatically and determine the correct handling strategy.

Error response structure

GraphQL errors appear in the errors array of the response, alongside any partial data that was successfully resolved. Each error object contains:

• message — a human-readable description of the error
• extensions.code — a machine-readable error code to use for programmatic handling
• path — which part of the query the error relates to

Additional properties may appear in extensions depending on the error type.

{
  "data": { "getProject": null },
  "errors": [
    {
      "message": "Entity not found",
      "extensions": {
        "code": "ENTITY_NOT_FOUND"
      },
      "path": ["getProject"]
    }
  ]
}

note

Always inspect both data and errors in every response. GraphQL can return partial data — some fields may resolve successfully while others produce errors. A non-null data object does not mean the request fully succeeded.

Authentication and authorization errors

These errors indicate a problem with the credentials or permissions used to make the request.

Code	When it occurs	How to handle
UNAUTHENTICATED	No auth token provided, token has expired, or token is invalid	Re-authenticate using createSessionUsingUserKey; redirect to login if in a UI context
UNAUTHORIZED	The authenticated user does not have the required role or permission for this operation	Check your account role and permissions with your account administrator
INSUFFICIENT_PERMISSIONS	The user's role does not grant access to the requested resource or operation	Check your role and permissions with your account administrator
FORBIDDEN	The action is explicitly forbidden for this account or role	Check whether the resource or operation requires elevated permissions
INCORRECT_USER_KEY_ID_OR_SECRET	The user key ID or secret provided for authentication is incorrect	Verify your key credentials; generate a new user key if needed

tip

Use UNAUTHENTICATED to trigger a re-authentication flow and UNAUTHORIZED or FORBIDDEN to show a permissions error to the user — these are distinct situations that warrant different responses in your application.

Resource errors

These errors relate to the resources being queried or mutated.

Code	When it occurs	How to handle
ENTITY_NOT_FOUND	The resource with the given ID does not exist or is not accessible to this account	Verify the ID is correct; check whether the resource has been deleted
CONFLICT	A duplicate resource would be created (e.g. a project name that is already taken in this account)	Use a different name or value; query existing resources first if needed

Validation errors

These errors indicate the request inputs did not pass validation.

Code	When it occurs	How to handle
BAD_USER_INPUT	Input fails schema validation — wrong type, missing required field, or malformed value	Read the message field for details about which input failed; compare against the schema
ARGUMENT_VALIDATION_ERROR	A resolver argument failed type-graphql validation rules	Read the message field for specific details about the validation failure

tip

When you receive BAD_USER_INPUT or ARGUMENT_VALIDATION_ERROR, read the message field carefully. It explains the constraint that was violated and which input is at fault.

Rate limit and quota errors

These errors indicate the request was rejected due to usage limits.

Code	When it occurs	How to handle
TOO_MANY_REQUESTS	Too many requests have been made within the current time window	Back off and retry using exponential backoff; see Rate Limits
ACCOUNT_CREDITS_DEPLETED	The account has run out of crawl credits	Upgrade your plan or contact support to increase limits

Pagination errors

Code	When it occurs	How to handle
EXCESSIVE_PAGINATION	The pagination depth or page size exceeds the allowed limit	Reduce the first or last value; use cursor-based pagination with smaller pages

Server errors

These errors indicate an unexpected failure on the server side.

Code	When it occurs	How to handle
SOMETHING_WENT_WRONG	An unexpected server-side error occurred	Retry with exponential backoff; if the error persists, contact support and include the operation name

Handling multiple errors

A single GraphQL request can return multiple errors — one for each field or input that failed. Inspect the full errors array rather than stopping at the first entry.

if (response.errors?.length) {
  const messages = [...new Set(response.errors.map(e => e.message))].join(", ");
  const codes = response.errors.map(e => e.extensions?.code);

  if (codes.includes("UNAUTHENTICATED")) {
    // Redirect to login or trigger token refresh
  } else {
    // Surface the error message to the user
    showError(messages);
  }
}

note

Using a Set when collecting messages deduplicates repeated errors, which is common when the same validation rule fails across multiple fields.

Network errors vs GraphQL errors

Not all failures produce a GraphQL error response. It is important to distinguish between the two:

• Network error — the request failed at the transport level (connection refused, DNS failure, timeout). No response body is available.
• HTTP error — some errors return a non-200 status code (e.g. HTTP 400 for malformed requests, HTTP 401 for invalid credentials). The response body may or may not contain an errors array. Always attempt to parse the response body even for non-200 responses.
• GraphQL error — the HTTP response is 200 OK but the errors array is present. The operation failed at the field level. The data object may still contain partial results for fields that did resolve successfully.

Always check both response.ok (or the HTTP status code) and response.errors in your client code.

tip

Treat a 200 OK response with a non-empty errors array as a partial failure. Do not assume success just because the HTTP status was 200.

Retrying safely

Not all errors are safe to retry. Retrying a request that will always fail wastes quota and delays your application.

Code	Safe to retry?	Notes
SOMETHING_WENT_WRONG	Yes	Use exponential backoff with a cap
TOO_MANY_REQUESTS	Yes	Wait for the rate limit window to reset before retrying
UNAUTHENTICATED	Yes, after token refresh	Refresh or re-obtain the session token first
ENTITY_NOT_FOUND	No	Fix the resource ID before retrying
UNAUTHORIZED	No	Check permissions or token validity
INSUFFICIENT_PERMISSIONS	No	A permissions change is required before retrying
FORBIDDEN	No	A permissions change is required before retrying
BAD_USER_INPUT	No	Fix the input validation error before retrying
ARGUMENT_VALIDATION_ERROR	No	Fix the argument that failed validation before retrying
EXCESSIVE_PAGINATION	No	Reduce page size before retrying
ACCOUNT_CREDITS_DEPLETED	No	A plan upgrade or credit top-up is required

warning

Blindly retrying non-retryable errors can consume your rate limit budget and result in TOO_MANY_REQUESTS errors on top of the original failure.