Errors

The Jobiflow API uses conventional HTTP status codes. Every error on a /public/v1/ endpoint answers with the same JSON body, ErrorDetails.

HTTP Status Codes

Error Body

{
  "errorCode": "INVALID_REQUEST",
  "message": "Invalid request",
  "statusCode": 400,
  "path": "/public/v1/job-listings",
  "timestamp": "2026-10-25T12:00:00.123",
  "fieldErrors": [
    { "field": "position", "message": "must not be null" }
  ]
}

Error Codes

A 400 that a service behind the API raises keeps that service's code, for example INVALID_JOBLISTING_STATUS_TRANSITION for a status change the listing cannot make.

A 404 therefore carries NOT_FOUND (or a resource's own code) when the endpoint exists but the resource does not, and INVALID_REQUEST when no endpoint has the path. The key is checked first: without a valid key every one of these answers 401 INVALID_API_KEY.

Handling Errors

const res = await fetch('https://api.jobiflow.com/public/v1/job-listings', {
  headers: { 'X-API-Key': process.env.JOBIFLOW_API_KEY },
});

if (!res.ok) {
  const err = await res.json();
  console.error(`[${err.errorCode}] ${err.message}`);

  for (const field of err.fieldErrors ?? []) {
    console.error(`  - ${field.field}: ${field.message}`);
  }

  throw new Error(err.errorCode);
}

const { data, pagination } = await res.json();

Rate Limits

Each API key may send 60 requests per minute and 10 per second. Beyond that the API answers 429 Too Many Requests with RATE_LIMIT_EXCEEDED and a Retry-After header: the number of seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 1