Error management

GraphQL convention

The GraphQL specification specifies the general format for returning errors : when a request causes one or more errors, the JSON response will contain an errors field, which will be a non-empty list of the errors encountered.

If the query resulted in an execution, the response will also contain a data field, as in the case of a query without errors.

Three types of errors can be distinguished :

• syntax errors

• schema errors

• application errors, which occur during the execution of the request

Syntax errors and schema errors block the execution of the request : the response will not contain a data field.

Syntax errors

Syntax errors cover all errors that prevent the GraphQL parser from interpreting the request. The HTTP code of the response will always be 400.

For example, there are errors in the constitution of the JSON :

POST /api/graphql HTTP/1.1
Host: sandbox.mobilic.beta.gouv.fr
Content-Type: application/json

{"Bad JSON"}

which will give this answer :

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "errors": [
    {
      "message":"POST body sent invalid JSON."
    }
  ]
{

There are also GraphQL syntax errors :

POST /api/graphql HTTP/1.1
Host: sandbox.mobilic.beta.gouv.fr
Content-Type: application/json

{
  "query": "wrongKeyword"
}

Response :

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "errors": [
    {
      "message":"Syntax Error GraphQL (1:1) Unexpected Name \"wrongKeyword\"\n\n1: wrongKeyword\n   ^\n",
      "locations": [
        {
          "line":1,
          "column":1
        }
      ]
    }
  ]
}

In the console, syntax errors are detected live and prevent the request from being submitted to the API.

Schema errors

Schema errors refer to requests that are syntactically correct but do not respect the schema of operations.

Since the syntax is correct, we only show the GraphQL operation in the following rather than the whole body of the HTTP request. As a reminder, the transition from the GraphQL operation to the HTTP POST request is explained here.

Same as the syntax errors, the HTTP code of the response is400.

Example

query {
  wrongOperation {
    someField
  }
}

Response

{
  "errors": [
    {
      "message": "Cannot query field \"wrongOperation\" on type \"Queries\".",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ]
    }
  ]
}

Variable validation errors

Type errors on operation variables are also considered as schema errors and give rise to the same responses.

Example

query {
  user(id: "not an integer") {
    firstName
  }
}

Response

{
  "errors": [
    {
      "message": "Argument \"id\" has invalid value \"not an integer\".\nExpected type \"Int\", found \"not an integer\".",
      "locations": [
        {
          "line": 2,
          "column": 12
        }
      ]
    }
  ]
}

In the console the response returned by the API to a request that causes a schema error is displayed encapsulated in an additional error field.

Application errors

Application errors are all errors that occur during the execution of the request.

The HTTP code of the response is 200 for this type of error.

Partial results

When errors occur at runtime, the response also includes a data field, which may contain partial results, depending on where the errors occurred.

Example

query {
  company(id: 1) {
    id
    name
    missions {
      id
    }
  }
}

Réponse

{
  "errors": [
    {
      "message": "Unauthorized access to field 'missions' of company object. Actor must be company admin.",
      "locations": [
        {
          "line": 5,
          "column": 5
        }
      ],
      "path": ["company", "missions"],
      "extensions": {
        "code": "AUTHORIZATION_ERROR"
      }
    }
  ],
  "data": {
    "company": {
      "id": 8,
      "name": "Mobilic Team",
      "missions": null
    }
  }
}

In the above case the response returned partial results because part of the operation did not trigger an error. For the parts that cause errors the corresponding field in the response will always have the value null.

Error codes

Each application error has a code, located in the extensions.code field of the error. These codes are used to classify errors. Here is the list of codes :

• INVALID_INPUTS : bad values taken by the operation variables, without type errors.

• AUTHENTICATION_ERROR : missing authentication data (e.g. no authorisation header) or invalid authentication data (wrong password, invalid access token).

• AUTHORIZATION_ERROR : accessing a resource or performing an operation for which the user does not have rights.

• INVALID_TOKEN : the invitation token is not valid (in the case of an invitation to join a company).

• OVERLAPPING_MISSIONS : overlap of two assignments in time for a mobile worker.

• OVERLAPPING_ACTIVITIES : overlap of two activities over time for a mobile worker.

• INVALID_ACTIVITY_SWITCH : the recording in tachograph mode has failed because there are subsequent recordings on date T.

• MISSION_ALREADY_ENDED : the mission has already been ended for the mobile worker.

• DUPLICATE_EXPENDITURES : recording a duplicate charge on the mission for a mobile worker.

• OVERLAPPING_EMPLOYMENTS : overlapping of two company attachments for a mobile worker.

• NO_PRIMARY_EMPLOYMENT : the user does not have a main attachment company, it is impossible to create a secondary attachment.

• INVALID_RESOURCE : impossibility to perform the requested operation on the object. Example: deletion of an activity that is already deleted.

• INTERNAL_ERROR : internal servor error