Error Reference

Errors

Comprehensive guide to API error codes, their meanings, and how to resolve them.

Quick Reference

All error status codes at a glance

Status	Code	Description
401	UNAUTHORIZED	The request is missing a valid API key, or the provided key has been revoked....
403	FORBIDDEN	The API key is valid but does not have the required permissions for this endpoin...
400	BAD_REQUEST	The request is malformed or missing required parameters....
404	NOT_FOUND	The requested resource does not exist....
422	UNPROCESSABLE_ENTITY	The request body is syntactically valid but contains semantic errors....
429	RATE_LIMITED	You have exceeded the request rate limit for your plan. Check the Retry-After he...
500	INTERNAL_ERROR	An unexpected error occurred on our servers. These are automatically reported an...
503	SERVICE_UNAVAILABLE	The API is temporarily unavailable, usually due to planned maintenance or high l...

Authentication Errors

401

UNAUTHORIZED

The request is missing a valid API key, or the provided key has been revoked.

Example Response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "status": 401
  }
}

Troubleshooting

Verify your API key is correct and active. Ensure you are using the Authorization header with the Bearer prefix: Authorization: Bearer tm_live_...

403

FORBIDDEN

The API key is valid but does not have the required permissions for this endpoint.

Example Response

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have 'prices.compare' permission.",
    "status": 403
  }
}

Troubleshooting

Check the permissions assigned to your API key in the dashboard. Add the required permission scope or generate a new key with the correct permissions.

Validation Errors

400

BAD_REQUEST

The request is malformed or missing required parameters.

Example Response

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Missing required parameter: drug_id",
    "status": 400,
    "details": {
      "field": "drug_id",
      "reason": "required"
    }
  }
}

Troubleshooting

Check the API documentation for required parameters. Ensure query parameters are correctly encoded and the request body (if any) is valid JSON.

404

NOT_FOUND

The requested resource does not exist.

Example Response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Drug with ID 'drug_999' not found.",
    "status": 404
  }
}

Troubleshooting

Verify the resource ID is correct. Use the search endpoint to find valid IDs. Note that resources may be removed if they are discontinued.

422

UNPROCESSABLE_ENTITY

The request body is syntactically valid but contains semantic errors.

Example Response

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Invalid postal code format. Expected Canadian format: A1A 1A1",
    "status": 422,
    "details": {
      "field": "postal_code",
      "reason": "format",
      "expected": "A1A 1A1"
    }
  }
}

Troubleshooting

Check that all field values match the expected formats documented in the API reference. Postal codes must be valid Canadian format (e.g., M5V 2H1).

Rate Limiting

429

RATE_LIMITED

You have exceeded the request rate limit for your plan. Check the Retry-After header for when you can retry.

Example Response

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. 1000/1000 requests used this minute.",
    "status": 429,
    "retry_after": 32
  }
}

Troubleshooting

Implement exponential backoff in your requests. Use the X-RateLimit-Remaining and Retry-After headers to pace your requests. Consider upgrading your plan for higher limits.

Server Errors

500

INTERNAL_ERROR

An unexpected error occurred on our servers. These are automatically reported and investigated.

Example Response

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal server error occurred. Please try again later.",
    "status": 500,
    "request_id": "req_abc123def456"
  }
}

Troubleshooting

Retry the request with exponential backoff. If the error persists, contact support with the request_id from the error response. Check the status page for any ongoing incidents.

503

SERVICE_UNAVAILABLE

The API is temporarily unavailable, usually due to planned maintenance or high load.

Example Response

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please try again in a few minutes.",
    "status": 503,
    "retry_after": 120
  }
}

Troubleshooting

Wait for the duration specified in the Retry-After header before retrying. Check the TransparentMedz status page for maintenance windows or incident reports.

General Error Handling Tips

Always check the HTTP status code before parsing the response body.
Implement exponential backoff for 429 and 5xx errors with jitter to avoid thundering herd problems.
Log the request_id from error responses for debugging and support requests.
Use the Retry-After header when present to determine optimal retry timing.
Never expose raw API error messages to end users in production applications.