The TalentLMS API uses standard HTTP status codes and a consistent JSON format for all error responses. This page describes how errors work and how to handle them.

Error response format

All API errors are returned as JSON. Include Accept: application/json in your request headers so the response is in this format.

Every error response includes:

• type — Either invalid_request_error (problem with the request) or api_error (server-side or unexpected issue).
• message — A short description of what went wrong.

Example:

{
  "type": "invalid_request_error",
  "message": "A required parameter is missing or an invalid type was supplied."
}

Use the HTTP status code for programmatic handling and the message (and optionally type) for logging or user feedback.

HTTP status codes

Success (2xx)

Code	Description
200	The request succeeded and a JSON response body is returned.
204	No content. The operation completed successfully and there is no response body (e.g. after a delete).

Client errors (4xx)

Code	Description
400	Bad request — A required parameter is missing, or an invalid type was supplied (e.g. a string where an integer is expected). Check the API Reference for required parameters and types.
401	Unauthorized — The API key is missing, incorrectly formatted, or invalid. Ensure you send a valid key in the X-API-Key header.
403	Forbidden — The API is not enabled for your domain, or the domain is inactive. Enable the API and check your domain in TalentLMS (Account & Settings → Integrations → API).
404	Not found — The requested resource does not exist (e.g. user, course, or branch ID not found). Verify IDs and that the resource hasn't been deleted.
422	Unprocessable entity — The request body or parameters are malformed and could not be processed.
429	Too many requests — You have exceeded the rate limit. Wait before retrying and use the rate-limit headers when present.

Server errors (5xx)

Code	Description
500	Internal server error — Something went wrong on TalentLMS's side. Retry later; if it persists, contact support.

Authentication errors (401)

You will receive 401 Unauthorized when:

• The X-API-Key header is missing.
• The API key is invalid or has been revoked.
• The API key is malformed.

Fix by generating a new API key in your TalentLMS site (Account & Settings → Integrations → API) and sending it in the X-API-Key header on every request.

HTTPS required

Requests must use HTTPS. If you call the API over plain HTTP, the server will respond with an error.

Rate limits

Rate limits cap how many API requests you can make per hour. Limits depend on your subscription plan (e.g. 2,000 or 10,000 requests per hour). In addition, requests must not exceed 200 calls per 5 seconds.

When you exceed the limit, the API returns 429 Too many requests. Response headers can help you throttle:

• X-RateLimit-Limit — Maximum requests allowed in the current window.
• X-RateLimit-Remaining — Requests left in the current window before hitting the limit.

Implement backoff and retry logic when you receive 429, and avoid bursts above 200 requests per 5 seconds.