Errors

The Picked API returns an error in the standard GraphQL format. This guide covers the shape of an error response, every error code, and what your code must do with each one.

Error response shape

When an operation fails, the API returns an errors array in the response body. Each error object holds these fields:

{
  "data": null,
  "errors": [
    {
      "message": "A human-readable description of the error",
      "path": ["mutationName"],
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

One response can hold more than one error. The data field is null when the whole operation failed. It holds part of the data when only some fields failed.

Authentication error codes

These errors come from a session, an account, OAuth, a magic link, a password operation, or MFA. They match the AuthErrorCode enum in the schema.

Example: invalid credentials

{
  "data": {
    "sessionCreate": {
      "session": null
    }
  },
  "errors": [
    {
      "message": "Invalid credentials",
      "path": ["sessionCreate"],
      "extensions": {
        "code": "INVALID_CREDENTIALS"
      }
    }
  ]
}

Authorization error codes

An authorization error happens when the caller does not hold the scope that an operation needs.

Example: the scope is not enough

A caller that holds organization/read only tries to delete an organization. It receives this:

{
  "data": {
    "organizationDelete": null
  },
  "errors": [
    {
      "message": "Insufficient permissions",
      "path": ["organizationDelete"],
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

Organization, member, and invitation error codes

These errors come from an organization, a member operation, or an invitation. They match the ErrorCode enum in the schema.

Organization errors

Member errors

Invitation errors

Project errors

General errors

What your code must do

Look for an error first

Check every response for an errors array before you read data:

const response = await fetch('/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
  body: JSON.stringify({ query, variables }),
});
 
const result = await response.json();
 
if (result.errors) {
  for (const error of result.errors) {
    const code = error.extensions?.code;
 
    switch (code) {
      case 'UNAUTHORIZED':
        // Send the user to the sign-in page.
        break;
      case 'FORBIDDEN':
        // Show a permissions error.
        break;
      case 'RATE_LIMITED':
        // Wait, then try again.
        break;
      default:
        // Put the message in the log, or show it.
        console.error(error.message);
    }
  }
}

Refresh a token that expired

A request can return UNAUTHORIZED while the caller holds a refresh token. Try a session refresh first. Do not treat it as a failure to sign in:

if (code === 'UNAUTHORIZED' && refreshToken) {
  const refreshResult = await sessionRefresh(refreshToken);
  if (refreshResult.session) {
    // Try the first request again with the new access token.
  } else {
    // Send the user to the sign-in page.
  }
}

Read data that is only part complete

GraphQL can return part of the data together with an error. Take a query that reads an organization and its members. It can succeed for the organization and fail for the members, when the caller does not hold organization_members/read. The response then holds data with the organization, and errors for the members field. Always read both.

Try again after a transient failure

INTERNAL_ERROR and RATE_LIMITED are both transient. For RATE_LIMITED, use an exponential backoff before you try again. For INTERNAL_ERROR, one more try is usually enough.

Related

• Authentication
• Your first API call