Thinkific’s GraphQL API returns errors as part of an array in the response body. Whereas REST APIs either succeed or fail, a GraphQL request can return partial responses alongside an error. Most graphQL responses return a 200 error code where you might expect a 4xx or 5xx from a REST API.
System errors and user errors are handled in different ways with Thinkific's GraphQL API:
- System/Validation errors are served using a top-level "errors" key
- User errors are served as part of the mutation response under the "data" key
In this article:
System/Validation Errors
When a request experiences either a system error or an error related to validation, we return a top level "errors" key using the following structure:
{
"data": {
"site": {
"owner": null
}
},
"errors": [
{
"message": "Sorry, something went wrong. Please contact support@thinkific.com and include this request ID 32858202-4212-49a4-9eb5-bfa11ea41a7b in your email.",
"locations": [
{
"line": 17,
"column": 5
}
],
"path": [
"site",
"courses"
],
"extensions": {
"code": "SERVER_ERROR",
"request_id": "32858202-4212-49a4-9eb5-bfa11ea41a7b"
}
}
]
}
Though not every error will include a `request_id`, please include any that you experience when contacting us to help us better debug the issue.
These errors may encompass anything from a system failure, such as (but not limited to):
- A request times out
- A request has an invalid argument
- A request is not authorized
User Errors
When a request experiences a user error, we serve a response as part of the mutation under the "data" key using the following structure:
{
"data": {
"createReply": {
"userErrors": [
{
"code": "NOT_ENROLLED",
"message": "User is not enrolled in the course containing this lesson",
"path": null
}
]
}
}
}
This error encompasses any kind of error where the user does something wrong, such as (but not limited to):
- A user attempts to create a new account using an existing email
- A user attempts to enroll a user in a class they're already enrolled in
When performing a mutation, you should always include the `userError` object under the `data` key in your request to ensure you capture any error responses:
mutation MarkLessonCompleteForCurrentUser {
markLessonComplete (input: {
lessonId: 123
}) {
lesson {
id
}
userErrors {
code
message
}
}
}
Error Codes
BAD USER INPUT
When a request does not include either a first or last argument, Thinkific will return a BAD_USER_INPUT error code.
{
"errors": [
{
"message": "You must pass either `first` or `last` to paginate the 'chapters' connection.",
"path": [
"site",
"courses",
],
"extensions": {
"code": "BAD_USER_INPUT"
}
}
],
"data": null
}
When a request's first or last argument exceeds the maximum allowed, Thinkific will return a BAD_USER_INPUT error code.
{
"errors": [
{
"message": "The maximum value for `first` or `last` is 100.",
"path": [
"site",
"users"
],
"extensions": {
"code": "BAD_USER_INPUT"
}
}
],
"data": null
}
FORBIDDEN
When a request is missing a relevant scope or is attempting to access a resource outside of the account's plan, Thinkific will return a FORBIDDEN error code.
{
"errors": [
{
"message": "Forbidden access",
"extensions": {
"code": "FORBIDDEN",
"serviceName": "thinkific",
"exception": {
"message": "Forbidden access",
"locations": [
{
"line": 1,
"column": 39
}
],
"path": [
"me"
]
}
}
}
],
"data": null
}
MAX_DEPTH_EXCEEDED
When a request's depth exceeds 15, Thinkific will return a MAX_DEPTH_EXCEEDED error code. See Query Limitations for more information regarding this.
{
"errors": [
{
"message": "Query depth of 15 exceeds the max depth limit",
"extensions": {
"code": "MAX_DEPTH_EXCEEDED"
}
}
]
}
NOT_FOUND
When a request accesses a resource that isn't available, Thinkific will return a NOT_FOUND error code. Thinkific will return `null` on any such requests.
{
"data": {
"lesson": null
}
}
MAX_QUERY_COST_EXCEEDED
When a single request exceeds a cost of 1000, Thinkific will return a MAX_QUERY_COST_EXCEEDED error code. See Query Limitations for more information regarding this.
{
"errors": [
{
"message": "Query cost of 1200 exceeds the maximum single query cost limit of 1000.",
"extensions": {
"code": "MAX_QUERY_COST_EXCEEDED"
"maxCost": 1000
}
}
],
"extensions": {
"rateLimit": {
"cost": 1200,
"remaining": 2000,
"resetAt": "2023-12-13T15:48:00.000Z",
"limit": 2000
}
}
}
RATE_LIMITED
When a request exceeds your rate limit, Thinkific will return a RATE_LIMITED error code. See Query Limitations for more information regarding this.
{
"errors": [
{
"message": "API rate limit exceeded.",
"extensions": {
"code": "RATE_LIMITED"
}
}
],
"extensions": {
"rateLimit": {
"cost": 104,
"remaining": 0,
"resetAt": "2023-12-13T15:48:00.000Z",
"limit": 2000
}
}
}
UNAUTHORIZED
When a request uses a deleted token, Thinkific will return 200 status code and an UNAUTHORIZED error code in the response.
For invalid or expired tokens, Thinkific will return a 401 status code and the following error message:
{
"message": "Unauthorized"
}