Errors

Errors use RFC 9457 problem details with Content-Type: application/problem+json. Branch on code: it is stable and never renamed. title and detail are for people and may be reworded.

{
  "type": "https://navapatra.com/docs/errors#invalid_input",
  "title": "Invalid input",
  "status": 400,
  "detail": "The request failed validation; see errors.",
  "code": "invalid_input",
  "requestId": "104cb9e8-3807-46aa-bfb9-4f62a03bc53f",
  "errors": [
    { "path": "birth.date", "message": "date must be YYYY-MM-DD" },
    { "path": "birth.place.lng", "message": "lat and lng are required unless query is given" }
  ]
}

Member	Always	Meaning
type	Yes	A link to the code’s section on this page
title	Yes	Short summary of the code
status	Yes	The HTTP status, repeated
detail	Yes	What went wrong in this request
code	Yes	Stable, machine-readable code
requestId	Yes	Same as the x-request-id header; quote it to support
errors	Sometimes	Field-level problems as { path, message }, with dotted paths into your request
candidates	Sometimes	Places to choose from, for ambiguous_place
details	Sometimes	Extra context, for ambiguous_local_time and out_of_range
topUpUrl	Sometimes	Where to buy credits, for insufficient_credits

No error response ever costs credits.

All codes

Status	Code	In short
400	invalid_input	The request is malformed or a value is invalid
400	unsupported_version	Unknown Navapatra-Version
401	unauthorized	Missing, invalid or revoked key or token
401	token_expired	The client token has expired
402	insufficient_credits	The organization has no credits
402	credit_cap_reached	A key or token cap is used up
403	secret_key_in_browser	A secret key was sent from a browser
403	origin_not_allowed	A publishable key was used from another origin
403	demo_restricted	Not available with the demo key
403	forbidden	The key or token may not call this endpoint
404	not_found	No such route
405	method_not_allowed	The path exists but not with this method
413	response_too_large	The response would exceed 512 KB
422	out_of_range	A date is outside the supported range
422	ambiguous_local_time	The local time is skipped or repeated by a clock change
422	ambiguous_place	The place name matches several places
422	place_not_found	The place name matches nothing
429	rate_limited	Too many requests
500	server_misconfigured	A server setting is missing
500	internal_error	Something failed on our side
503	service_unavailable	Credit checks, rate limiting or key validation are briefly unavailable

400

invalid_input

The body is not valid JSON, a POST body was sent without Content-Type: application/json, a field is missing or has the wrong type or format, or a value is impossible (such as BS month 5 day 33, AD 2025-02-30 or a tzid that is not an IANA time zone). errors lists each problem with a dotted path, for example birth.place.lng or pairs.3.female.birth.date.

Fix: correct the fields named in errors. Retrying unchanged will fail the same way.

unsupported_version

The Navapatra-Version header names a version that does not exist, for example Unknown Navapatra-Version "2020-01-01".

Fix: send a date listed in apiVersions from GET /v1/meta, or leave the header out to use your key’s pinned version. See Versioning.

401

unauthorized

No Authorization header, a header not in the form Bearer <value>, an unknown or revoked key, or an invalid client token.

Fix: send Authorization: Bearer <key>. Check the key has not been rolled or revoked in the dashboard. To try the API without a key, use demo.

token_expired

A client token (ct_) is past its expiresAt.

Fix: ask your backend for a new token and retry once. See Mobile apps.

402

insufficient_credits

The organization’s balance is 0. The response includes topUpUrl and x-credits-remaining: 0.

Fix: buy credits on the billing page, or wait for the monthly free grant on the first of the month (UTC). Test keys never hit this. See Credits.

credit_cap_reached

The key has used its monthly credit cap (“This key reached its monthly credit cap.”) or the client token has used its creditCap (“This client token reached its credit cap.”).

Fix: for a key, raise the cap in the dashboard or wait for the next UTC month. For a token, issue a new one if the user should continue.

403

secret_key_in_browser

An sk_live_ or sk_test_ key arrived with an Origin header, meaning it was sent from a browser.

Fix: move the call to your server. In browsers, use a pk_ key with an origin allowlist or a client token. If the key was ever in client-side code, roll it. See Authentication.

origin_not_allowed

A pk_ key was used without an Origin header or from an origin that is not on its allowlist.

Fix: add the exact origin (scheme, host and port, such as https://app.example.com) to the key’s allowlist in the dashboard.

demo_restricted

The demo key was used with a birth or place that is not one of the samples, with a kundali payload instead of birth input, or on an endpoint it cannot call (batch matching, panchang range, tokens, usage).

Fix: use one of the sample subjects, or sign up for a test key.

forbidden

The credential is valid but not allowed here: a client token calling an endpoint outside its scopes, a key other than sk_live_ calling POST /v1/tokens, or anything but a secret key (sk_live_ or sk_test_) calling GET /v1/usage.

Fix: add the endpoint id to the token’s scopes, or use the right key type.

404

not_found

No operation exists at that path, for example any unknown path under /v1. A known path called with the wrong method, such as GET /v1/kundali (it is a POST), gets 405 method_not_allowed instead, as does any method other than GET, HEAD and POST.

Fix: check the method and path in the API reference.

405

method_not_allowed

A request under /v1 used a method the path does not support: GET (or HEAD) on a POST operation such as /v1/kundali, POST on a GET operation, or a method other than GET, HEAD or POST, such as PUT or DELETE. The Allow header lists the methods that path accepts. HEAD works wherever GET does.

Fix: use the method shown for the operation in the API reference.

413

response_too_large

The response would be larger than 512 KB, usually a kundali with all vargas, every dasha system and levels: 3, or a long panchang range with choghadiya. detail suggests what to drop.

Fix: narrow include, lower options.dasha.levels, shorten the range, or split the request.

422

out_of_range

A birth date outside AD 1900-01-01 to 2100-12-31 (details.ad has the date), or a BS date that falls outside that window (BS 1956-09-19 to 2157-09-15).

Fix: check the date and its calendar. Supported ranges are listed in GET /v1/meta.

ambiguous_local_time

The birth’s local time is skipped (details.kind: "gap") or repeated ("overlap") by a daylight saving change. details.candidates holds both possible UTC instants.

Fix: ask which was meant and resend with options.disambiguation: "earlier" or "later". See Timezones.

ambiguous_place

place.query matches more than one place. candidates lists up to 10, each with name, admin1, country, lat, lng and tzid. The same rule sets ambiguous: true on a GET /v1/places/search response, so a place picker can ask before a birth request fails.

Fix: let the user choose and resend with that candidate’s lat and lng, or narrow the query: add a province or district after a comma ("Pokhara, Kaski"), or set place.country.

place_not_found

place.query matches nothing in the gazetteer. errors points at the field.

Fix: check the spelling, try GET /v1/places/search, or send lat and lng.

429

rate_limited

Too many requests for the bucket that applies, or a test key’s daily 100 is used up. The response has Retry-After in seconds.

Fix: wait Retry-After seconds and retry. See Rate limits.

500

server_misconfigured

A required server setting is missing, for example client tokens are not configured. This is a fault on our side.

Fix: contact hello@navapatra.com with the requestId.

internal_error

An unexpected failure. The request was not charged.

Fix: retry with backoff. If it persists, contact hello@navapatra.com with the requestId.

503

service_unavailable

A store the API depends on could not be reached in time:

• Credits. The store that holds your organization’s credits did not answer, and the request could not be served in degraded mode. During such an outage a key that made a successful call in the last 10 minutes keeps working, up to a small credit allowance per organization; any other key gets this error. GET /v1/usage answers this error while the store is down.
• Rate limiting. The per-IP limiter for the demo key and publishable (pk_) keys is down. These requests fail closed rather than run unlimited.
• Key validation. The key store is down and this key was not validated recently by the server handling the request.

The response has Retry-After in seconds and nothing is charged.

Fix: wait Retry-After seconds and retry with backoff.