Errors
Every API failure has the same JSON shape.
Shape
{
"error": {
"code": "insufficient_scope",
"message": "this API token doesn't have the write:offers scope",
"request_id": "6f1c…"
}
}code is stable: branch on it. message is for people and may change. request_id matches the X-Request-Id header; quote it when you contact PropFit. A 401 or 403 also carries a WWW-Authenticate header, and a 429 a Retry-After header.
Codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request is malformed: bad JSON, cursor, limit or Idempotency-Key. |
| 401 | unauthorized | No token, or a token PropFit doesn’t know. |
| 401 | token_revoked | The token was revoked, or its creator left or is no longer an owner or admin. |
| 401 | token_expired | The token has expired. Create a new one. |
| 403 | insufficient_scope | The token doesn’t have the scope this call needs. |
| 403 | not_entitled | The organization’s plan doesn’t include API access. |
| 403 | account_suspended | PropFit suspended the organization or the member who created the token. Contact PropFit support. |
| 403 | org_unverified | Match summaries need a verified organization. |
| 403 | forbidden | The call isn’t allowed for this organization or record. |
| 404 | not_found | No such record, or it belongs to another organization. |
| 405 | method_not_allowed | The path doesn’t support this HTTP method. |
| 409 | conflict | The record’s state doesn’t allow it, e.g. editing a vacancy that isn’t a draft, or a unit that already has a live vacancy. |
| 409 | idempotency_key_reused | This Idempotency-Key was used with a different request body. |
| 422 | validation_failed | A field is missing or invalid. The message says which. |
| 429 | rate_limited | Too many calls this minute. Retry after the Retry-After seconds. |
| 500 | internal_error | Something went wrong on PropFit’s side. Retry; quote the request_id if it persists. |
MCP tools
The MCP server returns the same codes inside a tool result marked isError: true, as code: message text.