Skip to main content
The API uses standard HTTP status codes to indicate the result of an authentication or request attempt. Below are the common error structures you may encounter.

​
HTTP Status Codes

​
400 Bad Request

Returned when variables are missing or the request is malformed. 
{
  "extensions": {
    "code": 400,
    "traceId": "06b0de7d2a"
  },
  "message": "expecting a value for non-nullable variable: \"external_id\""
}

​
401 Unauthorized

Returned when the access token is missing or invalid. 
{
  "extensions": {
    "code": 401,
    "traceId": "..."
  },
  "message": "..."
}
Resolution: Re-authenticate to obtain a new access token.

​
403 Forbidden

Returned when the provided token is expired or does not have sufficient permissions. 
{
  "extensions": {
    "code": 403,
    "traceId": "77020d7cb1"
  },
  "message": "Token has expired"
}

​
422 Unprocessable Entity

Returned when the request is well-formed but contains semantic errors or violates business rules (e.g., validation failures). 
{
  "extensions": {
    "code": 422,
    "traceId": "93bad0e604"
  },
  "message": "Candidate Creation failed"
}

​
429 Too Many Requests

Returned when the request frequency exceeds the allowed rate limit. 
{
  "extensions": {
    "code": 429,
    "traceId": "..."
  },
  "message": "..."
}
Resolution: Implement exponential backoff. For more details, see the Rate Limiting guide.

​
500 Internal Server Error

Returned when an unexpected error occurs on the Talview server. 
{
  "extensions": {
    "code": 500,
    "traceId": "93bad0e604"
  },
  "message": "Internal Server Error"
}

​
502 Server Timed Out

Returned when an upstream service did not respond in time. 
{
  "extensions": {
    "code": 502,
    "traceId": "..."
  },
  "message": "..."
}

​
Business Logic Errors

In GraphQL, a business rule violation may return an HTTP 200 OK status, but the success field within the data block will be false. 
{
  "data": {
    "booking_create": {
      "success": false,
      "error_message": "No available slots for selected date",
      "data": null
    }
  }
}

​
Common Logical Error Codes

These specific strings are often returned within the error_message field or GraphQL extensions block to provide granular detail:
ErrorDescriptionResolution
VALIDATION_ERRORInput data failed schema or logic checks.Review input parameters and constraints.
SLOT_UNAVAILABLEThe selected time slot is no longer available.Refresh slot availability and select a new slot.
BOOKING_NOT_FOUNDThe provided Booking ID does not exist.Verify the Booking ID is correct.
RESCHEDULE_NOT_ALLOWEDReschedule request violates business policy.Check reschedule eligibility windows.
PAYMENT_REQUIREDPayment is required before the action can proceed.Process the required payment transaction.
IDENTITY_VERIFICATION_FAILEDIdentity documents or photo failed verification.Review document quality and retry.

​
Best Practices

  1. Check success first: Always evaluate the success boolean before attempting to access the data object.
  2. Handle Actionable Errors: Display the error_message directly to users for errors like SLOT_UNAVAILABLE.
  3. Token Management: Automatically handle 401/403 errors by refreshing the OAuth2 access token.
  4. Logging: Log the traceId provided in the error response to assist Talview support in debugging.