Errors

The PCRecruiter REST API uses standard HTTP status codes to indicate the result of a request. A 2xx code means success; a 4xx code means the request was rejected because of something in the request (authentication, permissions, validation, or a missing record); a 5xx code means something went wrong on the PCRecruiter side.

HTTP Status Codes

Code	Meaning	Typical Cause
200 OK	Success	The request succeeded. For GET, the body contains the requested record(s). A POST that creates a new record also returns 200 (not 201), with the created record in the body.
400 Bad Request	Malformed request	The request was rejected before processing — for example, too many access-token requests in a short window (see Rate Limiting). Note that malformed search queries and unknown field names are not reported as 400; they surface as 500 (see below).
401 Unauthorized	Authentication failed	Missing, invalid, or expired session token. Generate a new session via the access-token endpoint.
403 Forbidden	Not permitted	The session is valid but the user lacks permission for this record, field, or operation.
404 Not Found	No such resource	The endpoint path is wrong, or the record ID does not exist in this database.
500 Internal Server Error	Server error	An unexpected error in PCRecruiter. This also covers request errors that aren't validated gracefully — notably invalid query syntax and unknown field names (e.g. a misspelled field in Query, Order, or Fields). A 500 from a malformed request will keep failing until you correct the request; a 500 from a well-formed request is a server-side problem — retry after a short delay, and if it persists contact support.

Error Response Body

A failed request returns one of two body shapes, depending on how the error was raised. Write your error handling to tolerate both.

Handled errors

Errors the API raises deliberately — authentication, permissions, not-found, validation it checks for — return a clean object. (If your request's Accept header asks for XML, the same fields are returned as an <errors> element with the pcrErrorCode attribute.)

{
  "errors": "A human-readable description of what went wrong.",
  "pcrErrorCode": "EXAMPLE"
}

Field	Type	Description
errors	string	A human-readable explanation of the failure. Intended for logs and developers, not end users — its wording may change, so don't match on it in code.
pcrErrorCode	string	A stable, machine-readable identifier for the error. Present only for errors that have a defined code; safe to branch on when it appears.

Unhandled exceptions

Some request errors — notably an invalid Query or an unknown field name do not contain the above shape. They surface as a 500 carrying the underlying Message and ExceptionMessage, not the errors/pcrErrorCode object above:

{
  "Message": "An error has occurred.",
  "ExceptionMessage": "Query missing operator after: FirstName foo",
  "ExceptionType": "System.ArgumentException"
}

Do not build logic against this shape — treat any 500 as opaque. The ExceptionMessage is useful while debugging your request, but a calling application should log the response and surface a generic failure rather than parsing it.

Handling Errors

A few practices that make integrations more robust:

• Branch on the status code first, then on pcrErrorCode. Status codes tell you the category; the error code tells you the specific cause. Avoid matching on errors text, which may change.
• Treat 401 as "re-authenticate." Session tokens are not permanent — they expire after a period of inactivity. The exact lifetime depends on the account's configuration. When you receive a 401, request a new session and retry once.
• Don't retry an error the request caused. A 400, 403, or 404 — and a 500 that came from a malformed query or bad field name — will fail again unless the request itself changes. Only a 500 on a request you know is well-formed is worth retrying.
• Back off on 5xx. Wait and retry with exponential backoff rather than hammering the endpoint.

Rate Limiting

Request quotas are governed by the App ID and API Key you authenticate with — each set of credentials is tied to a plan with its own rate limit. Know the limits that apply to yours, and design integrations to stay within them: avoid tight polling loops, and batch where possible.

Session creation is throttled separately, on top of any plan limit: requesting access tokens too rapidly is throttled. More than one token request inside a 10-second window is briefly delayed, and more than three in that window is rejected with a 400 Bad Request ("Too Many Access-Token Requests"). Authenticate once and reuse the session token for its lifetime rather than logging in per request.