Overview

The Postnomic API uses standard HTTP conventions for error reporting and includes rate limiting to ensure fair usage and platform stability. This guide covers how to handle errors and work within rate limits.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the outcome of each request:

Success Codes

Client Error Codes

Server Error Codes

ProblemDetails Format

All error responses use the ProblemDetails format (RFC 7807), providing structured error information:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Quota Exceeded",
  "status": 403,
  "detail": "Cannot create blog. Blog limit reached: 1 of 1 allowed on the Free plan.",
  "instance": "/api/blogs",
  "requestId": "0HN4ABCDEF123:00000001",
  "traceId": "00-abcdef1234567890abcdef1234567890-1234567890abcdef-01"
}

Key Fields

• type — A URI reference identifying the error type
• title — A short, human-readable summary of the problem
• status — The HTTP status code
• detail — A specific explanation of what went wrong and why
• requestId — A unique identifier for the request, useful for support inquiries
• traceId — An OpenTelemetry trace ID for distributed tracing and debugging

Quota-Related Errors (403)

When subscription quotas are exceeded, the API returns a 403 with a descriptive detail message:

{
  "title": "Quota Exceeded",
  "status": 403,
  "detail": "Cannot create post. Monthly post limit reached: 5 of 5 allowed on the Free plan."
}

Common quota errors include:

• Blog limit — "Cannot create blog. Blog limit reached: N of N allowed on the [Plan] plan."
• Post limit — "Cannot create post. Monthly post limit reached: N of N allowed on the [Plan] plan."
• Storage limit — "Cannot upload file. Storage quota exceeded. Current usage: X MB, Limit: Y MB."
• User limit — "Cannot add user. User limit reached: N of N allowed on the [Plan] plan."

To resolve quota errors, either delete existing resources or upgrade your subscription plan.

Rate Limiting

The Postnomic API implements rate limiting to prevent abuse and ensure fair access for all users.

Rate Limit Headers

When rate limiting is active, responses include headers indicating your current usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709312400

• X-RateLimit-Limit — Maximum requests allowed in the current window
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the rate limit window resets

When Rate Limited

If you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait until the reset time before retrying.

Retry Strategies

Exponential Backoff

For transient errors (429, 500, 503), implement exponential backoff:

int retryCount = 0;
int maxRetries = 3;

while (retryCount < maxRetries)
{
    var response = await httpClient.GetAsync(url);

    if (response.IsSuccessStatusCode)
        break;

    if (response.StatusCode == HttpStatusCode.TooManyRequests ||
        response.StatusCode >= HttpStatusCode.InternalServerError)
    {
        var delay = TimeSpan.FromSeconds(Math.Pow(2, retryCount));
        await Task.Delay(delay);
        retryCount++;
    }
    else
    {
        break; // Non-retryable error
    }
}

.NET Resilience

The Postnomic Client SDK uses .NET's built-in resilience features. If you are building a custom integration, consider using Microsoft.Extensions.Http.Resilience for automatic retry and circuit-breaker policies.

Debugging Tips

• Include the requestId and traceId from error responses when contacting support
• Check the detail field for specific guidance on resolving the error
• Use the Scalar API docs (available at /scalar in development) to test requests interactively