Errors

Every error has the same shape: a code for your code, a message for people, and sometimes details.

{
  "error": {
    "code": "validation_failed",
    "message": "Name can't be blank.",
    "details": { "name": ["can't be blank"] }
  }
}

Codes

Status	code	Means
400	invalid_parameter, invalid_json	A query parameter or the JSON body is malformed
401	unauthorized	No token, or a bad one (Authentication)
403	session_required	Only Nifty itself can do this, not a token
403	read_only	Nifty is read-only: the trial has ended with no licence that covers this version (Read-only)
404	not_found	No such record, or the ID isn't one
409	conflict, folder_not_empty, in_use, idempotency_key_in_use	It clashes with the record's state, or a retry is still running
411	length_required	An upload without Content-Length
413	payload_too_large	The body is too big
415	unsupported_media_type	The body isn't application/json
422	validation_failed	A field is wrong: see details
422	idempotency_key_reused, provider_error, key_required, already_added	See the endpoint's reference
429	rate_limited	Too many requests: wait
500	internal_error	Nifty failed. No details

Each endpoint in the reference lists the errors it can return (People, for example).

422: what was wrong

details maps each field (or base, for the record as a whole) to its problems, as phrases you can show beside the field. A 400 uses the same details for query parameters.

Read-only

When the free trial has ended without a licence that covers this version (a revoked key doesn't cover versions released after it was revoked), every POST, PUT, PATCH and DELETE gets 403 read_only. Every GET still works. The exceptions are the licence itself, your password, username and API tokens, appearance and update settings. A token can read the licence (GET /api/v1/licence, System) but can't change it: add or replace one from a signed-in session, in the app (Nifty → Licence…), or with nifty licence add on the server. A refused POST doesn't use up its Idempotency-Key.

Rate limits

Each IP address gets 300 API requests a minute. Past that, requests get 429 rate_limited with a Retry-After header saying how many seconds to wait. A few endpoints, such as checking for updates, have tighter limits of their own.

Reporting a problem

Every response has an X-Request-Id header, and the server's log names each request by it (journalctl -u nifty | grep <id>). Quote it when you ask for help.