Error Codes

Comprehensive reference for all error codes returned by the Texture REST API

Error Response Structure#

All error responses from the Texture REST API return a JSON body with at minimum a code and message field:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

Additional Fields#

Some error responses include extra fields alongside code and message:

Example: Standard Error#

{
  "code": "DEVICE_NOT_FOUND",
  "message": "The specified device does not exist"
}

Example: Validation Error with Details#

{
  "code": "VALIDATION_ERROR",
  "message": "The request body failed validation",
  "details": {
    "serialNumber": "Serial number is required",
    "capacity": "Must be a positive number"
  }
}

Example: Rate Limit Error#

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Try again later.",
  "retryAfter": 42
}

Example: Conflict with Mismatched Fields#

{
  "code": "PARAMETER_MISMATCH",
  "message": "A device with this manufacturer device ID already exists with different parameters",
  "mismatchedFields": ["serialNumber", "name"]
}

Authentication Errors (401)#

Returned when the API cannot verify the caller's identity.

Common causes#

• Missing Texture-Api-Key header
• Malformed API key value
• API key has been revoked or expired
• Using the wrong API key type for the endpoint (e.g., using a Management key on an OEM endpoint that requires a Manufacturer key)

Do not retry. Fix the API key and re-send.

Authorization Errors (403)#

Returned when the API key is valid but lacks permission for the requested operation.

Do not retry. Adjust your API key permissions or correct the request.

Validation Errors (400)#

Returned when the request data is invalid or the operation cannot be performed given the resource's current state.

Do not retry without modifying the request. Read the message and details fields to identify what needs to change.

Resource Not Found Errors (404)#

Returned when the specified resource does not exist or is not accessible with your current API key.

Verify the resource ID is correct. The resource may have been deleted, or your API key may not have access to the workspace that contains it.

Conflict Errors (409)#

Returned when the request conflicts with the current state of an existing resource.

Handling PARAMETER_MISMATCH#

This error is specific to OEM device creation (POST /devices). When you create a device and one with the same manufacturerDeviceId already exists, the API compares fields. If they all match, the call succeeds idempotently. If any fields differ, you receive PARAMETER_MISMATCH with a mismatchedFields array listing the differing fields.

Rate Limit Errors (429)#

Returned when the caller exceeds the API's request rate limits.

Rate Limit Response Headers#

Rate Limits by Operation Type#

Rate limits are applied per API key. Wait for the number of seconds in Retry-After, then retry. For sustained rate limiting, implement exponential backoff.

Server Errors (500, 502)#

Returned when an unexpected error occurs on the server side. These are never caused by your request data.

Retry with exponential backoff (1s → 2s → 4s). After 3–5 retries, stop and contact Texture support.

OEM Device Integration Errors#

Quick reference for OEM Direct Integration endpoints.

Device Creation — POST /devices#

Telemetry Push — POST /devices/

/telemetry#

HTTP Status Code Quick Reference#

* 404 may be retryable if the resource was very recently created (eventual consistency). A single retry after 1–2 seconds is reasonable.

Best Practices for Error Handling#

1. Branch on HTTP status code first. Use the status code to determine the error category, then inspect code for specifics.
2. Use code for programmatic handling. The code field is stable and machine-readable. Map code values to specific handling logic in your client.
3. Use message for logging only. The message field is human-readable and may change without notice. Do not parse it for control flow.
4. Retry only retryable errors. Only 429, 500, and 502 responses should be retried. All other status codes indicate a problem with the request itself.
5. Respect Retry-After. When present, always honor the Retry-After header before retrying.
6. Implement exponential backoff for server errors. Start at 1 second and double on each retry, up to a maximum of 3–5 attempts.
7. Log the full error response. Always log code, message, and any additional fields (details, mismatchedFields) for debugging.
8. Handle PARAMETER_MISMATCH explicitly in your device provisioning flow. This is an expected response when re-provisioning devices and should be handled as a recoverable conflict, not a generic error.
9. Monitor rate limit headers proactively. Check X-RateLimit-Remaining on successful responses to throttle your request rate before hitting 429.