Error Handling

When something goes wrong, the TempClock API returns a consistent error response format. This page covers every error code, what causes it, and how to fix it.

Error Response Format

All errors follow the same JSON structure, making them easy to handle in your code:

{ "error": true, "message": "A human-readable description of what went wrong.", "status": 400 }
Field Type Description
error boolean Always true for error responses.
message string A human-readable explanation of the error.
status integer The HTTP status code (matches the response header).

Error Code Quick Reference

Status Name Common Cause
400 Bad Request Missing or invalid parameters
401 Unauthorized Missing, invalid, or expired API key
403 Forbidden API not enabled or insufficient scope
404 Not Found Resource does not exist or belongs to another client
405 Method Not Allowed Wrong HTTP method for this endpoint
409 Conflict Worker already clocked in / no open clock-in to close
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Unexpected server-side error
400

Bad Request

The request could not be processed because of missing or invalid parameters. Check the message field for details on which parameter is invalid.

Common Causes

  • Missing required fields in a POST request body (e.g. worker_id, action)
  • Invalid date format (expected YYYY-MM-DD)
  • Invalid value for action (must be "in" or "out")
  • Malformed JSON in the request body

Example Response

{ "error": true, "message": "Missing required field: worker_id", "status": 400 }
How to fix: Verify all required fields are present and correctly formatted. Check the endpoint documentation for the expected parameter types and values.
401

Unauthorized

The request lacks valid authentication credentials. The API could not identify you based on the provided Authorization header.

Common Causes

  • No Authorization header included in the request
  • Using Token instead of Bearer prefix
  • API key has been revoked or deactivated in the manage portal
  • API key has passed its expiry date
  • Typo or truncation in the API key value

Example Responses

{ "error": true, "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>", "status": 401 }
{ "error": true, "message": "This API key has expired. Please create a new key.", "status": 401 }
How to fix: Ensure your request includes Authorization: Bearer YOUR_API_KEY. Verify the key is active in your manage portal under Settings > API Keys. If the key has expired or been revoked, contact TempClock to request a new one.
403

Forbidden

The API key is valid, but does not have permission to perform this action. This is different from 401 — the key is recognised, but access is denied.

Common Causes

  • API access has not been enabled for the account (contact TempClock)
  • The API key does not have the required scope for this endpoint (e.g. trying to use /clock.php without clock:write)

Example Responses

{ "error": true, "message": "API access is not enabled for this account. Contact your TempClock administrator.", "status": 403 }
{ "error": true, "message": "Insufficient permissions. This key does not have the 'clock:write' scope.", "status": 403 }
How to fix: For account-level access issues, contact TempClock to enable the API. For scope issues, contact TempClock to request a new key with the appropriate scopes, or a key with no scope restrictions (full access).
404

Not Found

The requested resource does not exist. For security reasons, the API also returns 404 when a resource exists but belongs to another client — you will never be told about resources outside your account.

Common Causes

  • The id parameter refers to a worker, location, or resource that does not exist
  • The resource belongs to a different client account
  • The resource was deleted

Example Response

{ "error": true, "message": "Worker not found.", "status": 404 }
How to fix: Verify the ID is correct by listing all resources first (e.g. call GET /workers.php to find valid worker IDs). Ensure the resource belongs to your account.
405

Method Not Allowed

The HTTP method used is not supported for this endpoint. The response includes an Allow header indicating which methods are accepted.

Common Causes

  • Sending a POST request to a GET-only endpoint (e.g. POST /workers.php)
  • Sending a GET request to a POST-only endpoint (e.g. GET /clock.php)
  • Using PUT or DELETE (not currently supported)

Example Response

HTTP/1.1 405 Method Not Allowed Allow: GET
{ "error": true, "message": "Method not allowed. Allowed: GET", "status": 405 }
How to fix: Check the Allow response header or the endpoint reference for the correct HTTP method.
409

Conflict

The request conflicts with the current state of the resource. This is specific to the /clock.php endpoint.

Common Causes

  • Attempting to clock in a worker who is already clocked in
  • Attempting to clock out a worker who has no open clock-in entry

Example Responses

{ "error": true, "message": "Worker is already clocked in.", "status": 409 }
{ "error": true, "message": "Worker has no open clock-in to close.", "status": 409 }
How to fix: Check the worker's current clock-in status before attempting to clock them in or out. Use the timesheets endpoint to query their latest entry, or handle the 409 response gracefully in your application.
429

Too Many Requests

You have exceeded the rate limit of 60 requests per minute for this API key. The response includes a Retry-After header indicating how many seconds to wait.

Example Response

{ "error": true, "message": "Rate limit exceeded. Maximum 60 requests per minute.", "status": 429 }
How to fix: Wait for the number of seconds specified in the Retry-After header before making another request. Implement exponential backoff for retries. See the Rate Limits page for best practices.
500

Internal Server Error

An unexpected error occurred on the server. This is not caused by your request — it indicates a problem on the TempClock side.

Example Response

{ "error": true, "message": "An unexpected error occurred. Please try again later.", "status": 500 }
How to fix: Retry the request after a short delay (5–10 seconds). If the error persists, contact TempClock support with the timestamp and endpoint that triggered the error.

Handling Errors in Your Code

Always check the HTTP status code of the response. For non-2xx codes, parse the error JSON and handle accordingly:

// Example: Error handling in JavaScript/Node.js const response = await fetch(url, { headers }); if (!response.ok) { const error = await response.json(); switch (response.status) { case 401: // Re-authenticate or refresh API key throw new Error(`Auth failed: ${error.message}`); case 429: // Wait and retry const retryAfter = response.headers.get('Retry-After') || 60; await sleep(retryAfter * 1000); return retryRequest(); default: throw new Error(`API Error ${error.status}: ${error.message}`); } }
Rate Limits Code Examples