Error Codes

Every API error returns a stable JSON envelope with a machine-readable code, an HTTP status, and a remediation URL. Branch on code, never on the human-readable message.

Error reference

Status	Title	Description	Common causes	Fix
400	Bad Request	The request body or query parameters are malformed.	Missing required fields in the JSON body Invalid parameter types (string instead of number) Malformed JSON syntax	Validate the request payload against the OpenAPI schema before sending.
401	Unauthorized	The request has no valid authentication credentials.	Missing Authorization header Expired or revoked API key Malformed Bearer token format	Include a valid developer key via Authorization: Bearer s2s_YOUR_KEY. Verify it with /api/developers/whoami.
403	Forbidden	The authenticated key does not have permission for this resource.	Accessing a workspace owned by another actor Key lacks the required scope for the endpoint Resource restricted to a higher tier	Check your key's scopes and actor context. Ensure you have access to the requested resource.
404	Not Found	The requested resource does not exist or has no matching record.	Invalid paper ID or arXiv reference Workspace ID that was deleted or never created Endpoint path is misspelled	Verify the resource identifier via a search endpoint before retrying.
429	Rate Limited	Too many requests in the current time window.	Exceeded per-minute or per-hour rate limit Burst of concurrent requests from the same key Automated retry loop without backoff	Implement exponential backoff. Check the Retry-After header for the recommended wait time.
500	Internal Server Error	An unexpected server-side failure occurred while processing the request.	Transient database or upstream service outage Unhandled edge case in the request payload Infrastructure deployment in progress	Retry with exponential backoff. If the error persists, report it with the request ID from the response headers.

Response format

Every error response uses a consistent JSON envelope. Parse the error.code field for programmatic branching and follow remediation_url for human-readable guidance.

{
  "error": {
    "code": "PAPER_PACK_NOT_FOUND",
    "message": "No paper found for arxiv_id 9999.99999v1.",
    "status": 404,
    "remediation_url": "https://sciencetostartup.com/developers/error-codes"
  }
}

Handling errors

Retry strategy

Use exponential backoff for 429 and 500 errors. Check the Retry-After header when present. Never retry 400, 401, or 403 errors without fixing the request first.

Branch on code, not message

The message field is for humans and may change without notice. Always branch your error handling on the stable code field.