Handling errors

Error format

Every error response is JSON with an error code and a message:

{
  "error": "invalid_token",
  "message": "Invalid token: access token is invalid"
}

• error is a stable snake_case code you can switch on.
• message is a human-readable explanation.
• 400 validation errors also include details with per-field messages.

A 401 Unauthorized means the request was not authenticated. A 403 Forbidden means the token was accepted, but the client is not allowed to access the resource.

Status	error	When
400	validation_error	Invalid request body or query
401	missing_token	Authorization header is missing
401	invalid_token	Bearer token is invalid, expired, or revoked
401	invalid_client	Wrong client ID or secret on POST /auth/token
401	unauthorized	Token is not associated with a user
403	inactive_user	The user is not active
403	forbidden	Wrong grant type, no linked company, or inaccessible resource
404	not_found	Unknown path
429	rate_limited	Rate limit exceeded
500	internal_error	Unexpected server error

Authentication Errors

Protected endpoints require a valid OAuth 2.0 access token.

Missing Token

If the Authorization header is missing, protected endpoints return 401 Unauthorized:

{
  "error": "missing_token",
  "message": "Access token is missing"
}

Include the token on every request except POST /auth/token and GET /health:

Authorization: Bearer <access_token>

Invalid or Expired Token

If the access token is invalid, expired, or revoked, protected endpoints return:

{
  "error": "invalid_token",
  "message": "Invalid token: access token is invalid"
}

If your access token has expired, request a new one. See Create Access Token.

If you receive the same error with a token you expect to be valid, verify that:

• The header uses the Bearer scheme and the token value is complete.
• The token has not been revoked or replaced.

Invalid Client Credentials

POST /auth/token does not use a Bearer token. If the client ID or client secret is wrong, the API returns:

{
  "error": "invalid_client",
  "message": "Invalid client credentials"
}

Confirm the credentials from your company page on goLance under OAuth Applications.

Unauthorized Token

In rare cases, a token is accepted but is not associated with a user. Protected endpoints then return:

{
  "error": "unauthorized",
  "message": "Unauthorized"
}

If this persists after requesting a new token, contact goLance Support.

Validation Errors

If the request body or query parameters fail validation, the API returns 400 Bad Request:

{
  "error": "validation_error",
  "message": "Input validation failed",
  "details": {
    "page": {
      "message": "Expected number, received nan"
    }
  }
}

Rate Limits

The API limits how many requests a client can send in a 1-minute window. Limits are counted per IP address, and POST /auth/token also counts per clientId. GET /health is not rate limited.

Scope	Limit	Applies to
IP address	200 requests per minute	All endpoints except GET /health
IP address	5 requests per minute	POST /auth/token
clientId	5 requests per minute	POST /auth/token

POST /auth/token is subject to both the global IP limit and the stricter auth limits. The lowest remaining limit is the one that applies.

When a limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": "rate_limited",
  "message": "Too many requests, please try again later."
}

Successful and rejected responses include rate-limit headers:

RateLimit-Limit: 200
RateLimit-Remaining: 0
RateLimit-Reset: 42
RateLimit-Policy: 200;w=60

A 429 response also includes Retry-After with the number of seconds to wait before retrying.

Recommended handling:

• Do not retry immediately. Wait for Retry-After, or until RateLimit-Reset seconds have passed.
• Cache the access token and reuse it until it expires (typically 1 hour). Do not call POST /auth/token on every request.

Server Errors (5xx)

If the API returns a 5xx status code (for example 500 Internal Server Error), it means that an unexpected error occurred on the goLance servers.

{
  "error": "internal_error",
  "message": "An unexpected error occurred"
}

These errors are usually temporary.

Recommended handling:

• Retry the request after a short delay (for example, 5–10 seconds).
• If the error persists, contact goLance Support and provide the request details (endpoint, timestamp, and response body if available).