Error Codes

How to interpret error codes to your requests to the Talview Graph API

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:

Error	Description	Resolution
VALIDATION_ERROR	Input data failed schema or logic checks.	Review input parameters and constraints.
SLOT_UNAVAILABLE	The selected time slot is no longer available.	Refresh slot availability and select a new slot.
BOOKING_NOT_FOUND	The provided Booking ID does not exist.	Verify the Booking ID is correct.
RESCHEDULE_NOT_ALLOWED	Reschedule request violates business policy.	Check reschedule eligibility windows.
PAYMENT_REQUIRED	Payment is required before the action can proceed.	Process the required payment transaction.
IDENTITY_VERIFICATION_FAILED	Identity 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.