Request IDs & Debugging

Every API response includes a unique request ID for tracing and debugging.

Where Request IDs Appear

Request IDs appear in two places:

1. Error Response Bodies

{
  "error": {
    "type": "not_found",
    "message": "Job job_01HV... not found",
    "request_id": "req_01HV..."
  }
}

2. Successful Response Headers

The request_id is available on all responses as a field in the response body (for errors) or can be correlated via your Idempotency-Key.

Using Request IDs

For Support Tickets

When reporting an issue, always include the request ID. It allows our team to find the exact request in our logs:

“I’m getting a 500 error when creating a job. Request ID: req_01HVAXYZ123”

For Debugging

Log request IDs alongside your application’s trace IDs:

const response = await fetch('https://api.firsthandapi.com/v1/jobs', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await response.json();
 
if (!response.ok) {
  console.error('API error', {
    status: response.status,
    requestId: body.error?.request_id,
    errorType: body.error?.type,
    message: body.error?.message,
  });
}

For Correlating Related Calls

When a workflow involves multiple API calls (create job → poll status → get files), log the request ID from each call to trace the full flow.

Request ID Format

Request IDs use the format req_01HV... (ULID with req_ prefix). They are globally unique and time-ordered — earlier requests have lexicographically smaller IDs.

Best Practices

• Always log request IDs from error responses
• Include in monitoring alerts so on-call can investigate quickly
• Store with your records — save the request ID when creating resources so you can trace the creation later
• Send in support tickets — “request ID: req_01HV…” is the fastest way to get help