Errors

When a request fails, the Pointeron API returns a consistent error envelope with a machine-readable error code, a human-readable message, and a request ID for support reference. This guide covers the error format, all error codes, and rate limit headers.

Error response format

All error responses follow the same envelope structure. Use the error field for programmatic handling and the message field for debugging or displaying to users.

Name
object
Type
string
Description
Always "error" for error responses.
Name
success
Type
boolean
Description
Always false for error responses.
Name
error
Type
string
Description
A machine-readable error code such as validation_error or not_found.
Name
message
Type
string
Description
A human-readable description of what went wrong.
Name
request_id
Type
string
Description
A unique identifier for this request, prefixed with req_. Include this when contacting support.

Error response

{
  "object": "error",
  "success": false,
  "error": "not_found",
  "message": "No asset found with ID ast_abc123.",
  "request_id": "req_7kR3mNpQ9xWv2tYs"
}

Error codes

Name
unauthorized
Type
401
Description
The API key is missing, malformed, or revoked. Check your Authorization or X-API-Key header.
Name
forbidden
Type
403
Description
The API key is valid but lacks the required scope, or the resource belongs to a different organization.
Name
device_disabled
Type
403
Description
The target device has been disabled. Re-enable it in the dashboard before sending data.
Name
not_found
Type
404
Description
The requested resource does not exist or has been deleted.
Name
validation_error
Type
422
Description
The request body failed validation. See the details array for field-level errors.
Name
rate_limit_exceeded
Type
429
Description
You have exceeded your rate limit. Wait until the Retry-After period elapses.
Name
internal_error
Type
500
Description
An unexpected error occurred on our side. If this persists, contact support with the request_id.

Validation errors

When a request fails with validation_error, the response includes a details array that lists each invalid field, the rule that failed, and a description.

Name
details
Type
array
Description
An array of objects, each with field, rule, and message keys describing a specific validation failure.

Validation error response

{
  "object": "error",
  "success": false,
  "error": "validation_error",
  "message": "The given data was invalid.",
  "request_id": "req_9pL2kRvX4mNwTjBs",
  "details": [
    {
      "field": "latitude",
      "rule": "required",
      "message": "The latitude field is required."
    },
    {
      "field": "longitude",
      "rule": "between",
      "message": "The longitude must be between -180 and 180."
    }
  ]
}

Rate limiting

The Pointeron API enforces per-key rate limits. Every response includes headers that tell you your current usage. When you exceed the limit, requests return 429 Too Many Requests until the window resets.

Name
X-RateLimit-Limit
Type
integer
Description
The maximum number of requests allowed in the current window.
Name
X-RateLimit-Remaining
Type
integer
Description
The number of requests remaining in the current window.
Name
X-RateLimit-Reset
Type
integer
Description
The UTC epoch timestamp (in seconds) when the current rate limit window resets.
Name
Retry-After
Type
integer
Description
Included only on 429 responses. The number of seconds to wait before retrying.

When you receive a 429 response, read the Retry-After header and wait that many seconds before retrying. Implement exponential backoff for production resilience.

429 Rate limit response

{
  "object": "error",
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 12 seconds.",
  "request_id": "req_4vN8tKwR2mLpXjQs"
}

Response headers

HTTP/2 429
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710415320
Retry-After: 12

Handling errors in code

const response = await fetch('https://api.pointeron.com/v2/assets', {
  headers: { 'Authorization': 'Bearer sk_live_your_api_key_here' },
})

if (!response.ok) {
  const error = await response.json()

  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After')
    console.log(`Rate limited. Retrying in ${retryAfter}s...`)
    // Wait and retry
  } else {
    console.error(`[${error.error}] ${error.message} (${error.request_id})`)
  }
}