Errors
Problem details responses, status codes, and rate limiting.
The Nimply API reports failures using problem details as defined by
RFC 9457. Error responses have the
Content-Type: application/problem+json header and a consistent body shape.
Problem details format
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
"type": "https://developers.nimply.io/errors/validation",
"title": "Validation failed",
"status": 422,
"detail": "scheduledAt must be an ISO 8601 datetime in the future.",
"instance": "/v1/posts/9f2b1c3d/schedule",
"errors": [
{ "field": "scheduledAt", "message": "must be in the future" }
]
}| Field | Meaning |
|---|---|
type | A URI identifying the error category |
title | Short, human-readable summary of the error category |
status | The HTTP status code, repeated in the body |
detail | Human-readable explanation specific to this occurrence |
instance | The request path that produced the error |
errors | (Validation errors only) per-field problems |
Status codes
| Status | Meaning |
|---|---|
400 | Malformed request (invalid JSON, wrong types) |
401 | Missing or invalid API key |
403 | Key is valid but lacks the required scope |
404 | Resource does not exist or belongs to another workspace |
409 | Conflict (e.g. replayed Idempotency-Key with a different body) |
422 | Request understood but failed validation |
429 | Rate limit exceeded — see below |
5xx | Something went wrong on Nimply's side; safe to retry with backoff |
Rate limits
Rate limits are applied per API key. Every response includes headers describing your current allowance:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window |
X-RateLimit-Remaining | Requests left in the current window |
Retry-After | (On 429 only) seconds to wait before retrying |
When you exceed the limit, the API responds with 429 Too Many Requests:
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 27
{
"type": "https://developers.nimply.io/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry after 27 seconds."
}Honor Retry-After and use exponential backoff with jitter for 5xx responses. Combine
retries with an Idempotency-Key on POST
requests so retried writes never create duplicates.