Error Handling

All API responses follow a consistent format:


{
  "jobId": null,
  "error": {
    "message": "Description of what went wrong"
  }
}

HTTP Status Codes

Code	Meaning	When
`200`	Success	Operation completed
`201`	Created	Job created via upsert (PUT when job didn’t exist)
`400`	Bad Request	Missing required fields or invalid data
`401`	Unauthorized	Missing `x-api-key` header
`403`	Forbidden	Invalid API key or not authorized for this resource
`404`	Not Found	Job with the given external ID not found
`409`	Conflict	Job with this ID already exists (use PUT to update)
`500`	Server Error	Internal error — contact Jobzyn support


{
  "error": {
    "message": "Please provide an API key"
  }
}

Fix: Add the x-api-key header to your request.


{
  "error": {
    "message": "Invalid API key"
  }
}

Fix: Check that your API key is correct and has not been revoked.


{
  "error": {
    "message": "Job ID is required"
  }
}

Fix: Include an id field in your job payload.


{
  "error": {
    "message": "Job with external id REQ-2024-001 already exists"
  }
}

Fix: Use PUT /api/integrations/job/REQ-2024-001 to update the existing job.


{
  "error": {
    "message": "External id REQ-2024-001 is not associated with any job within company 100"
  }
}

Fix: Verify the job ID is correct and was created with your API key.