Reference

Errors and versioning

Errors use the problem details format (RFC 9457). Besides the HTTP status, most errors have a stable code you can program against; detail is for people and may change.

Example

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Conflict",
  "status": 409,
  "detail": "The reviewer was already invited for this article.",
  "code": "reviewer_unavailable"
}

Error codes

HTTP	code	Meaning
400	—	The body is not valid JSON or a field breaks a rule. errors lists the fields.
401	`invalid_api_key`	The API key is missing, wrong or disabled.
402	`overage_cap_reached`	The overage cap of your institution is reached; no new invitations this period.
403	`account_suspended`	The institution account is suspended. Contact Scholvet.
403	`account_pending`	The institution account is waiting for verification: searches work (up to 100 a day per journal); invitations and registering reviewers do not yet.
429	`pending_search_limit`	Daily search limit for accounts waiting for verification. It goes away when the account is activated.
404	`search_not_found`	The search does not exist or belongs to another journal.
404	`invitation_not_found`	The invitation does not exist or belongs to another journal.
409	`search_expired`	The search is older than 30 days. Search again.
409	`reviewer_unavailable`	The reviewer was already invited for this article, or is no longer available (capacity, leave or a new conflict of interest).
409	`invalid_status`	The action is not possible in the invitation's current status.
422	`reviewer_not_in_search`	The reviewer code is not a result of that search.
429	—	More than 120 requests in a minute with this key.
5xx	—	A problem on our side. Retry later with the same request.

Validation error

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Keywords": ["The field Keywords must be a string or array type with a minimum length of '1'."]
  }
}

Versioning

Within v1, fields may be added to responses but are never removed or renamed. Ignore fields you do not know.
New event types and new values for status and declineReason may appear. Handle unknown values gracefully.
A breaking change is published as /api/v2. v1 keeps working, and you are told well in advance before it is retired.

OpenAPI description

A machine-readable description of v1, for generating clients and for testing tools: https://api.scholvet.com/openapi/v1.json

Handling reviewer data

Keep reviewer codes and scores inside your editorial system. Do not show them to authors.
A reviewer's identity is shared with you for the review they accepted. Use it for that review and your journal's editorial work only.
Do not try to link codes across journals or to identify reviewers from search results.
Every search, invitation and decision is logged on Scholvet with the key that made it.